Smartdevs17 · Ebuka321 · Jul 25, 2026 · Jul 25, 2026
diff --git a/docs/ADMIN_DASHBOARD.md b/docs/ADMIN_DASHBOARD.md
@@ -0,0 +1,61 @@
+# Admin Dashboard
+
+## Overview
+
+The admin dashboard provides administrators with comprehensive controls for managing merchants, subscriptions, users, analytics, and system health monitoring.
+
+## Features
+
+### Merchant Management
+- View all registered merchants with status indicators
+- Suspend or reactivate merchants (admin-only)
+- View merchant revenue and active plan counts
+
+### Subscription CRUD
+- Create, read, update, and delete subscriptions
+- Bulk pause selected subscriptions
+- Role-based access: analysts and admins can modify; support is read-only
+
+### User Management
+- View all users with their roles
+- Rotate user roles (admin-only)
+- Role hierarchy: viewer → analyst → support → admin
+
+### Analytics & Reporting
+- Payment success rate monitoring
+- Transaction volume and gas usage tracking
+- Active alert management
+
+### System Health Monitoring
+- API response time tracking
+- Database connection status
+- Memory usage monitoring
+- Service uptime tracking
+
+### Audit Logging
+- Immutable audit trail for all administrative actions
+- Filterable by resource type, action, or actor
+- Hash-chain integrity for tamper detection
+
+## Role-Based Access Control
+
+| Action | Admin | Analyst | Support |
+|--------|-------|---------|---------|
+| View merchants | ✅ | ✅ | ✅ |
+| Suspend merchant | ✅ | ❌ | ❌ |
+| Create subscription | ✅ | ✅ | ❌ |
+| Bulk pause | ✅ | ✅ | ❌ |
+| Delete subscription | ✅ | ❌ | ❌ |
+| Rotate user roles | ✅ | ❌ | ❌ |
+| View audit log | ✅ | ✅ | ✅ |
+
+## Navigation
+
+The admin dashboard is accessible from the Settings tab at route `AdminDashboard`. It requires authentication.
+
+## Technical Details
+
+- **Screen**: `src/screens/AdminDashboardScreen.tsx`
+- **Service**: `src/services/adminDashboardService.ts`
+- **Monitoring**: `backend/services/shared/monitoring.ts`
+- **Audit Types**: `backend/services/shared/auditTypes.ts`
diff --git a/docs/MERCHANT_ONBOARDING.md b/docs/MERCHANT_ONBOARDING.md
@@ -0,0 +1,85 @@
+# Merchant Onboarding with KYC
+
+## Overview
+
+The merchant onboarding system provides a multi-step wizard for KYC (Know Your Customer) verification, enabling merchants to start accepting subscription payments.
+
+## Onboarding Flow
+
+### Step 1: Business Information
+- Business name (required)
+- Business type (LLC, Corporation, etc.)
+- Country of operation
+- Phone number
+- Email address (required)
+
+### Step 2: ID Document Upload
+- Front of government-issued ID
+- Back of government-issued ID
+- Document verification status tracking
+
+### Step 3: Business License
+- Business license upload
+- Supporting documentation
+
+### Step 4: Review & Submit
+- Summary of all provided information
+- Document count verification
+- Submit for verification review
+
+## KYC Verification Tiers
+
+### Basic Tier
+- Monthly volume limit: $10,000
+- Max transactions: 100
+- Standard verification
+
+### Enhanced Tier
+- Monthly volume limit: $1,000,000
+- Max transactions: 10,000
+- Enhanced due diligence required
+
+## Onboarding Statuses
+
+| Status | Description |
+|--------|-------------|
+| `not_started` | Merchant has not begun onboarding |
+| `in_progress` | Merchant is completing steps |
+| `pending_review` | Submitted, awaiting admin review |
+| `verified` | KYC verification approved |
+| `rejected` | Verification denied |
+| `expired` | Verification window expired |
+
+## Onboarding Analytics
+
+Track key metrics:
+- **Completion rate**: Percentage of merchants who complete all steps
+- **Drop-off rate**: Where merchants abandon the process
+- **Average time to verify**: Duration from submission to decision
+- **Document rejection rate**: Percentage of documents rejected
+
+## Progress Tracking
+
+The step indicator component shows:
+- Current step highlighted
+- Completed steps with checkmark
+- Step labels for clarity
+
+## Notifications
+
+Merchants receive notifications for:
+- Step completion reminders
+- Verification status changes
+- Document rejection with reasons
+- Approval confirmation with tier assignment
+
+## Navigation
+
+Accessible from Settings tab at route `MerchantOnboarding`. Requires authentication.
+
+## Technical Details
+
+- **Screen**: `src/screens/MerchantOnboardingScreen.tsx`
+- **Store**: `src/store/merchantStore.ts`
+- **Types**: `src/types/merchant.ts`
+- **KYC Service**: `backend/services/shared/` (KYC integration)
diff --git a/docs/NAVIGATION.md b/docs/NAVIGATION.md
@@ -0,0 +1,142 @@
+# Navigation Architecture
+
+## Overview
+
+SubTrackr uses a feature-based modular navigation architecture built on React Navigation 6. The navigation is organized into feature-specific stack navigators, each handling a distinct domain of the application.
+
+## Architecture
+
+### Module Structure
+
+```
+src/navigation/
+├── AppNavigator.tsx          # Main navigator with tab and stack configuration
+├── types.ts                  # TypeScript types for routes and params
+├── navigationRef.ts          # Typed navigation ref for external navigation
+├── linking.ts                # Deep linking configuration
+├── analytics.ts              # Navigation analytics tracking
+├── benchmark.ts              # Navigation performance benchmarks
+├── NavigationErrorBoundary.tsx  # Error boundary for navigation
+└── modules/
+    ├── SubscriptionStack.tsx # Subscription management screens
+    ├── AnalyticsStack.tsx    # Analytics and reporting screens
+    ├── SettingsStack.tsx     # Settings and preferences screens
+    ├── AdminStack.tsx        # Admin dashboard screens
+    ├── WalletStack.tsx       # Wallet and invoice screens
+    ├── DeveloperStack.tsx    # Developer tools screens
+    └── SocialStack.tsx       # Community and social features
+```
+
+### Feature Modules
+
+| Module | Purpose | Screens |
+|--------|---------|---------|
+| SubscriptionStack | Subscription lifecycle | Add, Detail, Edit, Change Plan, Cancel, Pause, Usage |
+| AnalyticsStack | Analytics & reporting | Analytics, Revenue, Performance, Churn |
+| SettingsStack | App settings | Settings, Language, Notifications, Privacy, Tax |
+| AdminStack | Admin operations | Dashboard, Merchants, Fraud, Billing, SLA |
+| WalletStack | Payments & invoices | Wallet, Crypto, Invoices, Payments, Calendar |
+| DeveloperStack | Developer tools | Portal, Sandbox, API Keys, Docs, Webhooks |
+| SocialStack | Community features | Community, Profile, Gamification, Loyalty, Groups |
+
+### Tab Navigator
+
+The bottom tab navigator provides 6 primary entry points:
+
+1. **HomeTab** - HomeStack with subscription management
+2. **AddTab** - Quick add subscription
+3. **WalletTab** - Wallet and payment management
+4. **AnalyticsTab** - Analytics dashboard
+5. **RevenueTab** - Revenue reporting
+6. **SettingsTab** - Settings and admin
+
+## Lazy Loading
+
+All screens except the Home screen use lazy loading via `dynamic import()` wrapped in `lazyScreen()`. This ensures:
+
+- Faster initial load time
+- Reduced memory footprint
+- Code splitting per feature module
+
+```typescript
+const SubscriptionDetailScreen = lazyScreen(
+  () => import('../screens/SubscriptionDetailScreen')
+);
+```
+
+## Feature Gating
+
+Routes can be gated by feature flags and subscription tiers:
+
+```typescript
+const routeFeatureMap: Partial<Record<keyof RootStackParamList, FeatureId>> = {
+  CryptoPayment: FeatureId.CRYPTO_INTEGRATION,
+  Analytics: FeatureId.ADVANCED_ANALYTICS,
+};
+```
+
+## Auth Gating
+
+Protected routes require authentication:
+
+```typescript
+const authRequiredRoutes: Set<keyof RootStackParamList> = new Set([
+  'Profile',
+  'AdminDashboard',
+  'MerchantOnboarding',
+]);
+```
+
+## Deep Linking
+
+The app supports deep linking with URL prefixes:
+- `subtrackr://`
+- `https://subtrackr.app`
+
+### URL Patterns
+
+| Pattern | Route |
+|---------|-------|
+| `/home` | HomeTab |
+| `/subscriptions/:id` | SubscriptionDetail |
+| `/settings/admin` | AdminDashboard |
+| `/wallet/connect` | WalletConnect |
+| `/analytics` | AnalyticsTab |
+
+## Error Handling
+
+The `NavigationErrorBoundary` component catches navigation errors and provides a graceful fallback UI with retry capability.
+
+## Analytics
+
+Navigation analytics track:
+- Screen views with previous screen context
+- Navigation actions
+- Navigation errors
+- Deep link usage
+- Screen render performance
+
+## Performance Benchmarks
+
+Target metrics:
+- Screen render: < 250ms (p95)
+- Navigation transition: < 300ms
+- Deep link resolution: < 500ms
+- Tab bar response: < 100ms
+
+## Testing
+
+Navigation tests verify:
+- Analytics event tracking
+- Screen metric calculations
+- Navigation path building
+- Event limits and clearing
+
+## Adding a New Screen
+
+1. Create the screen component in `src/screens/`
+2. Add route to `RootStackParamList` in `types.ts`
+3. Add lazy import in the appropriate module stack
+4. Register in `AppNavigator.tsx` if needed for direct access
+5. Add deep link path in `linking.ts` if applicable
+6. Add feature gate if tier-restricted
diff --git a/docs/TRIAL_MANAGEMENT.md b/docs/TRIAL_MANAGEMENT.md
@@ -0,0 +1,46 @@
+# Trial Management
+
+## Overview
+
+SubTrackr provides a comprehensive trial management system with lifecycle tracking, conversion optimization, and A/B testing support.
+
+## Trial Lifecycle
+
+1. **Start** - A trial is created with `startTrial(subscriptionId, duration)`, setting status to `ACTIVE`.
+2. **Extend** - Active trials can be extended using `extendTrial(trialId, ruleId)` if extension rules allow.
+3. **Convert** - Trials transition to `CONVERTED` via `convertTrial(trialId)` when the user subscribes.
+4. **Expire** - Trials auto-expire via `autoConvertEligibleTrials()` or manually via `expireTrial(trialId)`.
+
+## Extension Rules
+
+Extension rules define how trials can be extended:
+
+- **maxExtensions**: Maximum number of times a trial can use this rule.
+- **extensionDurationDays**: Number of days added per extension.
+- **conditions**: Optional constraints (`minDaysRemaining`, `maxExtensionsUsed`, `requiredConversionEvents`).
+
+Rules are managed in the trial store via `addExtensionRule()`.
+
+## Conversion Funnel
+
+The system tracks funnel events:
+`trial_started` → `feature_accessed` → `dashboard_visited` → `payment_clicked` → `payment_completed` → `trial_converted`
+
+Use `getTrialAnalytics()` for drop-off rates, time-to-convert, and per-variant stats.
+
+## Notifications
+
+`TrialNotificationService` handles scheduling:
+- **Expiring soon**: Sent when trial has ≤3 days remaining.
+- **Extended**: Sent on trial extension.
+- **Expired/Converted**: Sent on status transitions.
+
+## Analytics
+
+`getTrialAnalytics()` returns:
+- Conversion/expiry/cancellation rates
+- Average time to convert/expire
+- Funnel step conversion rates
+- Drop-off analysis between funnel steps
+- Daily conversion counts
+- Per A/B test variant statistics