andrei/maternal-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Update admin dashboard plan with microservice architecture and invite codes
Some checks failed
ParentFlow CI/CD Pipeline / Backend Tests (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Frontend Tests (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Security Scanning (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Build Docker Images (map[context:maternal-app/maternal-app-backend dockerfile:Dockerfile.production name:backend]) (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Build Docker Images (map[context:maternal-web dockerfile:Dockerfile.production name:frontend]) (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Deploy to Development (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Deploy to Production (push) Has been cancelled
Details
CI/CD Pipeline / Build Application (push) Has been cancelled
Details
CI/CD Pipeline / Lint and Test (push) Has been cancelled
Details
CI/CD Pipeline / E2E Tests (push) Has been cancelled
Details

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Andrei
2025-10-06 21:30:23 +00:00
parent 0efa7ad6ec
commit df7617638a
1 changed files with 485 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

532
docs/ADMIN_DASHBOARD_IMPLEMENTATION.md
View File

@@ -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 (
<div>
{/* Global toggle */}
<Card>
<h3>Registration Settings</h3>
<Switch
label="Require invite code for registration"
checked={requireInvite}
onChange={setRequireInvite}
/>
<Text>Currently: {requireInvite ? 'Invite only' : 'Open registration'}</Text>
</Card>
{/* Code generator */}
<Card>
<h3>Generate Invite Codes</h3>
<Form>
<Input label="Prefix" placeholder="BETA-2025" />
<Select label="Type">
<option value="single">Single use</option>
<option value="multi">Multi-use</option>
<option value="unlimited">Unlimited</option>
</Select>
<Input label="Max uses" type="number" />
<DatePicker label="Expires at" />
<MultiSelect label="Platform restrictions">
<option value="web">Web</option>
<option value="ios">iOS</option>
<option value="android">Android</option>
</MultiSelect>
<Input label="Quantity" type="number" defaultValue="1" />
<Button>Generate Codes</Button>
</Form>
</Card>
{/* Codes list */}
<DataTable
columns={[
{ key: 'code', label: 'Code' },
{ key: 'type', label: 'Type' },
{ key: 'uses', label: 'Uses', render: (row) => `${row.current_uses}/${row.max_uses || '∞'}` },
{ key: 'platforms', label: 'Platforms' },
{ key: 'expires_at', label: 'Expires' },
{ key: 'actions', label: 'Actions' }
]}
data={inviteCodes}
/>
</div>
);
}
```
### 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<ValidationResult> {
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<RegistrationConfig> {
// 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)