From df7617638a2d060c22e9154499246a1f150e76e9 Mon Sep 17 00:00:00 2001 From: Andrei Date: Mon, 6 Oct 2025 21:30:23 +0000 Subject: [PATCH] feat: Update admin dashboard plan with microservice architecture and invite codes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Redesigned as standalone microservice for managing web and mobile apps - Added invite code registration system with enable/disable toggle - Service will be deployed on separate server (10.0.0.241) - Admin service at admin.parentflowapp.com - Added database schema for invite codes and usage tracking - Platform-specific code validation (web, iOS, Android) - Service-to-service authentication for secure communication - Batch code generation and export functionality - Analytics for tracking invite code effectiveness Architecture benefits: - Centralized control for all ParentFlow platforms - Independent scaling and deployment - Better security isolation for admin functions - Support for future mobile app management 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/ADMIN_DASHBOARD_IMPLEMENTATION.md | 532 ++++++++++++++++++++++--- 1 file changed, 485 insertions(+), 47 deletions(-) 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)