diff --git a/docs/ADMIN_DASHBOARD_IMPLEMENTATION.md b/docs/ADMIN_DASHBOARD_IMPLEMENTATION.md
index 3c04bbe..b137ca9 100644
--- a/docs/ADMIN_DASHBOARD_IMPLEMENTATION.md
+++ b/docs/ADMIN_DASHBOARD_IMPLEMENTATION.md
@@ -1,8 +1,9 @@
# Admin Dashboard Implementation Plan
-**Created**: October 3, 2025
-**Status**: Planning Phase
-**Priority**: High - Multi-tenancy & Administration
+**Created**: October 3, 2025
+**Updated**: October 6, 2025 - Separate microservice architecture
+**Status**: Planning Phase
+**Priority**: High - Multi-tenancy & Administration
**Estimated Effort**: 6-8 weeks (120-160 hours)
---
@@ -10,17 +11,27 @@
## 📋 Executive Summary
### Overview
-Create a comprehensive admin dashboard for managing the Maternal App with role-based access control (RBAC), user management, system monitoring, and configuration.
+Create a comprehensive **standalone admin service** for managing ParentFlow applications across multiple platforms (web, iOS, Android) with role-based access control (RBAC), user management, system monitoring, and configuration. This service will be deployed independently and manage all ParentFlow instances centrally.
+
+### Architecture Decision
+The admin dashboard will be implemented as a **separate microservice** to:
+- Manage both web and future mobile applications
+- Scale independently from main application
+- Provide centralized control across all platforms
+- Enable separate deployment and security policies
+- Support multi-tenant administration
### Key Features
-1. **User Management**: CRUD operations, data export, anonymization
-2. **Role-Based Access Control**: Parent, Guest, Admin roles
-3. **Multi-Profile Support**: Multiple families and account switching
-4. **Analytics Dashboard**: Usage metrics, AI/voice analytics
-5. **System Health Monitoring**: Service status, performance metrics
-6. **LLM Configuration**: Model settings, API keys, pricing
-7. **Content Management**: Legal pages, subscriptions
-8. **Email Configuration**: Mailgun settings management
+1. **Invite Code Registration System**: Control user registration with invite codes
+2. **User Management**: CRUD operations, data export, anonymization
+3. **Role-Based Access Control**: Parent, Guest, Admin roles
+4. **Multi-Platform Support**: Manage web, iOS, and Android users
+5. **Multi-Profile Support**: Multiple families and account switching
+6. **Analytics Dashboard**: Cross-platform usage metrics, AI/voice analytics
+7. **System Health Monitoring**: Service status across all platforms
+8. **LLM Configuration**: Model settings, API keys, pricing
+9. **Content Management**: Legal pages, subscriptions
+10. **Email Configuration**: Mailgun settings management
### Goals
- **Security**: Strict admin authentication and audit logging
@@ -32,58 +43,83 @@ Create a comprehensive admin dashboard for managing the Maternal App with role-b
## 🏗️ Architecture Overview
-### System Architecture
+### Microservice Architecture
```
┌─────────────────────────────────────────────────────────────┐
-│ Admin Dashboard UI │
-│ (maternal-web/admin/) │
+│ ParentFlow Admin Service │
+│ (Standalone Application) │
+│ admin.parentflowapp.com │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
-│ │ Users │ │ Analytics │ │ System │ │
-│ │ Management │ │ Dashboard │ │ Health │ │
+│ │ Invite │ │ Users │ │ Analytics │ │
+│ │ Codes │ │ Management │ │ Dashboard │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
-│ │ LLM │ │ Pages │ │ Email │ │
-│ │ Settings │ │ Management │ │ Settings │ │
+│ │ Platform │ │ System │ │ LLM │ │
+│ │ Manager │ │ Health │ │ Settings │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
- ▼
-┌─────────────────────────────────────────────────────────────┐
-│ Admin API (NestJS) │
-│ /api/v1/admin/* endpoints │
-│ │
-│ ┌──────────────────────────────────────────────────────┐ │
-│ │ AdminGuard (Role: Admin Only) │ │
-│ └──────────────────────────────────────────────────────┘ │
-│ │
-│ Modules: │
-│ • UserManagementModule │
-│ • RoleManagementModule │
-│ • AnalyticsAdminModule │
-│ • SystemHealthModule │
-│ • LLMConfigModule │
-│ • ContentManagementModule │
-│ • SubscriptionManagementModule │
-│ • EmailConfigModule │
-└─────────────────────────────────────────────────────────────┘
+ Service-to-Service
+ Communication
│
- ▼
+ ┌─────────────────────┼─────────────────────┐
+ ▼ ▼ ▼
+┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+│ ParentFlow │ │ ParentFlow │ │ ParentFlow │
+│ Web │ │ iOS │ │ Android │
+│ (NestJS) │ │ (Swift) │ │ (Kotlin) │
+├──────────────┤ ├──────────────┤ ├──────────────┤
+│ Validates │ │ Validates │ │ Validates │
+│ invite codes │ │ invite codes │ │ invite codes │
+│ with admin │ │ with admin │ │ with admin │
+│ service │ │ service │ │ service │
+└──────────────┘ └──────────────┘ └──────────────┘
+ │ │ │
+ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
-│ Database Layer │
+│ Shared Database Infrastructure │
│ │
-│ • users (with role field) │
-│ • user_profiles (multi-profile support) │
-│ • family_memberships (role per family) │
-│ • admin_audit_log (all admin actions) │
-│ • llm_config (model settings) │
-│ • subscription_plans │
-│ • email_config │
+│ • users (cross-platform) │
+│ • invite_codes (registration control) │
+│ • platform_sessions (web/ios/android tracking) │
+│ • admin_audit_log (all admin actions) │
+│ • system_configurations (per-platform settings) │
└─────────────────────────────────────────────────────────────┘
```
+### Admin Service Components
+
+```
+parentflow-admin-service/
+├── src/
+│ ├── modules/
+│ │ ├── invite-codes/ # Invite code generation & validation
+│ │ ├── user-management/ # Cross-platform user management
+│ │ ├── platform-manager/ # Web/iOS/Android platform configs
+│ │ ├── analytics/ # Unified analytics across platforms
+│ │ ├── system-health/ # Monitor all platform services
+│ │ ├── llm-config/ # AI configuration
+│ │ ├── subscriptions/ # Subscription management
+│ │ └── audit/ # Audit logging
+│ ├── common/
+│ │ ├── guards/ # Authentication guards
+│ │ ├── interceptors/ # Service communication
+│ │ └── decorators/ # Custom decorators
+│ └── database/
+│ └── migrations/ # Admin-specific migrations
+├── admin-ui/ # React admin dashboard
+│ ├── pages/
+│ │ ├── invite-codes/ # Manage invite codes
+│ │ ├── users/ # User management
+│ │ ├── platforms/ # Platform-specific settings
+│ │ └── analytics/ # Analytics dashboard
+│ └── components/
+│ └── shared/ # Shared UI components
+└── docker-compose.admin.yml # Separate deployment
+
---
## 👥 Role-Based Access Control (RBAC)
@@ -147,6 +183,262 @@ enum UserRole {
---
+## 🎟️ Invite Code Registration System
+
+### Overview
+Control user registration through invite codes to limit initial app access. This feature allows controlled rollout and beta testing across all platforms (web, iOS, Android).
+
+### Features
+- **Generate invite codes**: Batch or individual generation
+- **Code types**: Single-use, multi-use, unlimited
+- **Expiration dates**: Time-limited codes
+- **Platform restrictions**: Limit codes to specific platforms
+- **Usage tracking**: See who used which code
+- **Enable/Disable**: Toggle registration requirement globally
+
+### Database Schema
+
+```sql
+-- Invite codes table
+CREATE TABLE invite_codes (
+ id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+ code VARCHAR(20) UNIQUE NOT NULL, -- e.g., "BETA-2025-X7K9"
+ type VARCHAR(20) NOT NULL, -- 'single', 'multi', 'unlimited'
+ max_uses INTEGER DEFAULT 1, -- NULL for unlimited
+ current_uses INTEGER DEFAULT 0,
+ platform_restrictions VARCHAR(20)[], -- ['web', 'ios', 'android'] or NULL for all
+ expires_at TIMESTAMP,
+ metadata JSONB, -- Custom data: { "campaign": "beta", "referrer": "influencer1" }
+ created_by UUID REFERENCES users(id),
+ is_active BOOLEAN DEFAULT true,
+ created_at TIMESTAMP DEFAULT NOW(),
+ updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_invite_codes_code ON invite_codes(code);
+CREATE INDEX idx_invite_codes_active ON invite_codes(is_active) WHERE is_active = true;
+
+-- Invite code usage tracking
+CREATE TABLE invite_code_usage (
+ id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+ invite_code_id UUID NOT NULL REFERENCES invite_codes(id),
+ used_by_user_id UUID NOT NULL REFERENCES users(id),
+ platform VARCHAR(20) NOT NULL, -- 'web', 'ios', 'android'
+ device_info JSONB,
+ ip_address INET,
+ used_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_invite_code_usage_code ON invite_code_usage(invite_code_id);
+CREATE INDEX idx_invite_code_usage_user ON invite_code_usage(used_by_user_id);
+
+-- System configuration for registration
+CREATE TABLE registration_config (
+ id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+ require_invite_code BOOLEAN DEFAULT false,
+ registration_enabled BOOLEAN DEFAULT true,
+ custom_message TEXT, -- Message shown when registration is disabled
+ whitelist_domains VARCHAR(255)[], -- Email domains that bypass invite requirement
+ updated_by UUID REFERENCES users(id),
+ updated_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### API Endpoints
+
+#### Admin Endpoints
+
+```typescript
+// Admin Service API
+POST /api/v1/admin/invite-codes // Generate codes
+GET /api/v1/admin/invite-codes // List all codes
+GET /api/v1/admin/invite-codes/:id // Get code details
+PATCH /api/v1/admin/invite-codes/:id // Update code
+DELETE /api/v1/admin/invite-codes/:id // Deactivate code
+GET /api/v1/admin/invite-codes/:id/usage // Get usage history
+
+// Batch operations
+POST /api/v1/admin/invite-codes/batch // Generate multiple codes
+POST /api/v1/admin/invite-codes/export // Export codes as CSV
+
+// Configuration
+GET /api/v1/admin/registration/config // Get registration settings
+PATCH /api/v1/admin/registration/config // Update settings
+```
+
+#### Application Endpoints (Web/Mobile)
+
+```typescript
+// Public endpoint for all platforms
+POST /api/v1/auth/validate-invite-code
+{
+ "code": "BETA-2025-X7K9",
+ "platform": "ios"
+}
+
+// Response
+{
+ "valid": true,
+ "message": "Code accepted",
+ "metadata": {
+ "campaign": "beta"
+ }
+}
+
+// Registration endpoint (modified)
+POST /api/v1/auth/register
+{
+ "email": "user@example.com",
+ "password": "...",
+ "inviteCode": "BETA-2025-X7K9", // Required if enabled
+ "platform": "web"
+}
+```
+
+### Admin UI Components
+
+```typescript
+// pages/invite-codes/page.tsx
+export default function InviteCodesPage() {
+ const [requireInvite, setRequireInvite] = useState(false);
+
+ return (
+
+ {/* Global toggle */}
+
+ Registration Settings
+
+ Currently: {requireInvite ? 'Invite only' : 'Open registration'}
+
+
+ {/* Code generator */}
+
+ Generate Invite Codes
+
+
+
+ {/* Codes list */}
+ `${row.current_uses}/${row.max_uses || '∞'}` },
+ { key: 'platforms', label: 'Platforms' },
+ { key: 'expires_at', label: 'Expires' },
+ { key: 'actions', label: 'Actions' }
+ ]}
+ data={inviteCodes}
+ />
+
+ );
+}
+```
+
+### Implementation in Main Application
+
+```typescript
+// src/modules/auth/auth.service.ts (ParentFlow Web/API)
+@Injectable()
+export class AuthService {
+
+ async register(dto: RegisterDto) {
+ // Check if invite codes are required
+ const config = await this.getRegistrationConfig();
+
+ if (config.requireInviteCode) {
+ if (!dto.inviteCode) {
+ throw new BadRequestException('Invite code is required for registration');
+ }
+
+ // Validate with admin service
+ const validation = await this.adminService.validateInviteCode(
+ dto.inviteCode,
+ dto.platform || 'web'
+ );
+
+ if (!validation.valid) {
+ throw new BadRequestException(validation.message || 'Invalid invite code');
+ }
+
+ // Track usage
+ await this.adminService.recordInviteCodeUsage(
+ dto.inviteCode,
+ userId,
+ dto.platform
+ );
+ }
+
+ // Continue with normal registration...
+ }
+
+ private async getRegistrationConfig() {
+ // Cache this for performance
+ return await this.adminService.getRegistrationConfig();
+ }
+}
+```
+
+### Mobile Integration
+
+```swift
+// iOS - RegistrationViewController.swift
+func validateInviteCode(_ code: String) async throws -> Bool {
+ let response = try await AdminAPI.validateInviteCode(
+ code: code,
+ platform: "ios"
+ )
+ return response.valid
+}
+
+func register() async throws {
+ // Check if invite code is required
+ if registrationConfig.requireInviteCode {
+ guard let inviteCode = inviteCodeTextField.text, !inviteCode.isEmpty else {
+ throw RegistrationError.inviteCodeRequired
+ }
+
+ // Validate before proceeding
+ let isValid = try await validateInviteCode(inviteCode)
+ if !isValid {
+ throw RegistrationError.invalidInviteCode
+ }
+ }
+
+ // Continue with registration
+}
+```
+
+### Analytics & Reporting
+
+Track invite code effectiveness:
+- **Conversion rate**: Codes generated vs. used
+- **Platform distribution**: Usage by platform
+- **Time to use**: Average time from generation to use
+- **Referral tracking**: Which campaigns/sources are most effective
+- **Geographic distribution**: Where users are registering from
+
+---
+
## 🗄️ Database Schema Changes
### New Tables
@@ -1051,6 +1343,152 @@ export class EmailConfigService {
---
+## 🚀 Deployment Strategy
+
+### Admin Service Deployment
+
+The admin service will be deployed as a **separate microservice**:
+
+#### Infrastructure
+```yaml
+# docker-compose.admin.yml
+version: '3.8'
+
+services:
+ admin-api:
+ build: ./parentflow-admin-service
+ container_name: parentflow-admin-api
+ ports:
+ - "4000:4000" # Admin API on separate port
+ environment:
+ NODE_ENV: production
+ DATABASE_URL: postgresql://...
+ JWT_SECRET: ${ADMIN_JWT_SECRET}
+ SERVICE_AUTH_KEY: ${SERVICE_AUTH_KEY} # For service-to-service auth
+ networks:
+ - parentflow-network
+
+ admin-ui:
+ build: ./parentflow-admin-service/admin-ui
+ container_name: parentflow-admin-ui
+ ports:
+ - "4001:3000" # Admin UI
+ environment:
+ REACT_APP_API_URL: http://admin-api:4000
+ networks:
+ - parentflow-network
+
+networks:
+ parentflow-network:
+ external: true
+```
+
+#### Service Communication
+
+```typescript
+// Service-to-service authentication
+export class AdminServiceClient {
+ private readonly serviceKey: string;
+ private readonly adminApiUrl: string;
+
+ constructor() {
+ this.serviceKey = process.env.SERVICE_AUTH_KEY;
+ this.adminApiUrl = process.env.ADMIN_API_URL || 'http://localhost:4000';
+ }
+
+ async validateInviteCode(code: string, platform: string): Promise {
+ const response = await axios.post(
+ `${this.adminApiUrl}/api/v1/internal/validate-invite-code`,
+ { code, platform },
+ {
+ headers: {
+ 'X-Service-Auth': this.serviceKey,
+ 'X-Service-Name': 'parentflow-web'
+ }
+ }
+ );
+ return response.data;
+ }
+
+ async getRegistrationConfig(): Promise {
+ // Cache this for 5 minutes
+ return this.cache.get('registration-config', async () => {
+ const response = await axios.get(
+ `${this.adminApiUrl}/api/v1/internal/registration-config`,
+ {
+ headers: {
+ 'X-Service-Auth': this.serviceKey,
+ 'X-Service-Name': 'parentflow-web'
+ }
+ }
+ );
+ return response.data;
+ }, 300); // 5 minutes TTL
+ }
+}
+```
+
+#### Nginx Configuration
+
+```nginx
+# admin.parentflowapp.com
+server {
+ listen 443 ssl http2;
+ server_name admin.parentflowapp.com;
+
+ # SSL configuration
+ ssl_certificate /etc/letsencrypt/live/admin.parentflowapp.com/fullchain.pem;
+ ssl_certificate_key /etc/letsencrypt/live/admin.parentflowapp.com/privkey.pem;
+
+ # IP whitelist for admin access (optional)
+ allow 10.0.0.0/24; # Office network
+ allow 192.168.1.0/24; # VPN
+ deny all;
+
+ # Admin UI
+ location / {
+ proxy_pass http://localhost:4001;
+ proxy_http_version 1.1;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Connection 'upgrade';
+ proxy_set_header Host $host;
+ proxy_cache_bypass $http_upgrade;
+ }
+
+ # Admin API
+ location /api/ {
+ proxy_pass http://localhost:4000;
+ proxy_http_version 1.1;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ }
+}
+```
+
+### Deployment Servers
+
+```
+Production Environment:
+├── Admin Service
+│ ├── Server: 10.0.0.241 (separate from main app)
+│ ├── URL: admin.parentflowapp.com
+│ ├── Ports: 4000 (API), 4001 (UI)
+│ └── Database: Shared with main app (read/write to admin tables)
+│
+├── Main Applications
+│ ├── Web: 10.0.0.240:3030 → web.parentflowapp.com
+│ ├── API: 10.0.0.240:3020 → api.parentflowapp.com
+│ └── Mobile APIs: Will connect to api.parentflowapp.com
+│
+└── Shared Infrastructure
+ ├── PostgreSQL: 10.0.0.240:5432
+ ├── Redis: 10.0.0.240:6379
+ └── MongoDB: 10.0.0.240:27017
+```
+
+---
+
## 🚀 Implementation Timeline
### Phase 1: Foundation (Week 1-2)