System Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           MyStoryFlow System Architecture                        │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              Frontend Applications                              │
├─────────────────────────────────────────────────────────────────────────────────┤
│  Web App                Marketing Site         Admin App                        │
│  app.mystoryflow.com    mystoryflow.com       admin.mystoryflow.com            │
│                                                                                 │
│  Docs App               Tools App              Content-OS (Internal)            │
│  docs.mystoryflow.com   tools.mystoryflow.com                                  │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                               Shared Packages                                  │
├─────────────────────────────────────────────────────────────────────────────────┤
│  @mystoryflow/ui     │  @mystoryflow/auth     │  @mystoryflow/database         │
│  @mystoryflow/shared │  @mystoryflow/analytics│  @mystoryflow/admin            │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              Backend Services                                  │
├─────────────────────────────────────────────────────────────────────────────────┤
│  Next.js API Routes     │     Supabase Database     │     Supabase Storage     │
│  (Serverless Functions)│     & Authentication       │     (File Management)    │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                             External Services                                  │
├─────────────────────────────────────────────────────────────────────────────────┤
│  OpenAI/Gemini/Claude │    Stripe        │    Resend    │    Backblaze B2   │
│  (AI Processing)      │    (Payments)    │    (Email)   │    (File Storage) │
│  Notion API           │                  │              │    ElevenLabs TTS │
└─────────────────────────────────────────────────────────────────────────────────┘
``` -->

## Technology Stack

### Frontend

- **Framework**: Next.js 15.3.2 with App Router
- **Language**: TypeScript 5.x for type safety
- **Runtime**: React 19.0.0
- **Styling**: Tailwind CSS 4.x for utility-first styling
- **UI Components**: Custom component library with Radix UI primitives
- **State Management**: React hooks, context, and Zustand for complex state
- **Rich Text Editing**: TiptapEditor with extensive extensions for story editing

### Backend

- **Database**: Supabase (PostgreSQL) with Row-Level Security
- **Authentication**: Supabase Auth with social providers (Google, Apple), magic links
- **API**: Next.js API routes (serverless functions)
- **File Storage**: Supabase Storage + Backblaze B2 for scalability

### Infrastructure

- **Hosting**: Vercel for frontend applications
- **Database**: Supabase cloud infrastructure
- **CDN**: Vercel Edge Network
- **Monitoring**: Vercel Analytics + Supabase Dashboard
- **Build Tool**: Turbo 2.x for monorepo orchestration

### External Integrations

- **AI Processing**:
  - OpenAI GPT-4o-mini and GPT-4-turbo for content generation and refinement
  - Google Gemini (2.0-flash-exp, 1.5-flash, 1.5-pro) for multimodal processing and speech-to-text
  - Anthropic Claude (via @anthropic-ai/sdk) for advanced AI features
- **Payments**: Stripe for subscription and one-time payments
- **Email**: Resend for transactional emails
- **Additional Storage**: Backblaze B2 for large file storage (audio, images, documents)
- **Content Management**: Notion API for blog content integration

## Application Architecture

### 1. **Web App** (`app.mystoryflow.com`)

The main application where users create stories, manage campaigns, and collaborate with family members.

**Key Features:**

- Voice recording and transcription
- AI-powered story enhancement
- Memory book creation and customization
- Family collaboration and sharing
- Subscription management

### 2. **Marketing Site** (`mystoryflow.com`)

Public-facing website with marketing content, blog, and user acquisition flows.

**Key Features:**

- Landing pages and product information
- Blog with Notion CMS integration
- Waitlist and lead capture
- Gift purchase flows

### 3. **Admin App** (`admin.mystoryflow.com`)

Internal dashboard for managing users, monitoring system health, and administrative tasks.

**Key Features:**

- User management and support
- System monitoring and analytics
- Content moderation
- Administrative controls

### 4. **Docs App** (`docs.mystoryflow.com`)

Technical documentation site built with Next.js 15 and Nextra 4.x theme for internal and external documentation.

**Key Features:**

- API documentation with interactive examples
- Architecture guides and system design docs
- Development setup instructions
- Best practices and coding guidelines
- MDX-powered content with Mermaid diagrams
- Syntax highlighting with rehype-highlight

### 5. **Tools App** (`tools.mystoryflow.com`)

AI-powered productivity tools and learning applications available to all users.

**Key Features:**

- AI flashcard generator with multiple input methods
- Story prompt generation tools
- Export functionality (PDF, Anki, CSV, Quizlet, JSON)
- Game mode for interactive learning
- Public/private sharing with short codes
- Anonymous and authenticated user support

### 6. **Content-OS App** (Internal)

Agent-OS inspired content automation system for multimedia content generation.

**Key Features:**

- Automated blog article generation (Notion blocks)
- Image generation pipeline (Pinterest, Instagram, video scenes)
- Multi-platform video script generation (TikTok, Reels, Shorts, LinkedIn, Twitter, Facebook)
- Podcast episode generation with conversational AI
- Distribution planning for Pinterest waterfall campaigns
- ManyChat automation integration

## Data Architecture

### Database Design

Our PostgreSQL database is designed with the following key principles:

1. **Row-Level Security (RLS)**: Every table implements RLS policies to ensure data isolation between users and organizations
2. **Normalized Schema**: Proper normalization to reduce data redundancy and maintain consistency
3. **Audit Trails**: Comprehensive logging of data changes for compliance and debugging
4. **Performance Optimization**: Strategic indexing and query optimization

### Key Entities

- **Users**: Authentication and profile information
- **Organizations**: Multi-tenant structure for families/groups
- **Stories**: Core content entities with versioning
- **Campaigns**: Collaborative storytelling projects
- **Memory Books**: Generated PDF outputs
- **Subscriptions**: Payment and billing information

## Security Architecture

### Authentication & Authorization

- **Identity Provider**: Supabase Auth with social login support (Google, Apple)
- **Session Management**: JWT tokens with cross-app session transfer
- **Role-Based Access**: Granular permissions based on user roles (`user`, `admin`, `support`)
- **Magic Link Authentication**: Passwordless OTP-based login

### Data Protection

- **Encryption at Rest**: Database-level encryption via Supabase
- **Encryption in Transit**: TLS 1.3 for all communications
- **Row-Level Security**: Database-enforced access controls
- **Data Anonymization**: GDPR-compliant data handling

### API Security

- **Rate Limiting**: Protection against abuse and DoS attacks
- **Input Validation**: Comprehensive sanitization and validation
- **CORS Configuration**: Proper cross-origin resource sharing
- **Security Headers**: Implementation of security best practices

## Scalability Considerations

### Horizontal Scaling

- **Serverless Functions**: Automatic scaling based on demand
- **Database Scaling**: Supabase handles database scaling automatically
- **CDN Distribution**: Global edge caching via Vercel

### Performance Optimization

- **Code Splitting**: Lazy loading and dynamic imports
- **Image Optimization**: Next.js Image component with WebP support
- **Caching Strategy**: Multi-layer caching (browser, CDN, database)
- **Database Optimization**: Query optimization and proper indexing

### Monitoring & Observability

- **Error Tracking**: Comprehensive error logging and alerting
- **Performance Monitoring**: Real-time performance metrics
- **User Analytics**: Privacy-compliant usage tracking
- **Health Checks**: Automated system health monitoring

## Deployment Strategy

### Continuous Integration/Continuous Deployment (CI/CD)

- **Selective Deployment**: Only changed applications are rebuilt and deployed
- **Environment Promotion**: Staging → Production deployment pipeline
- **Rollback Capability**: Quick rollback mechanisms for failed deployments
- **Feature Flags**: Gradual feature rollouts and A/B testing

### Infrastructure as Code

- **Configuration Management**: Version-controlled infrastructure configuration
- **Environment Parity**: Consistent environments across development, staging, and production
- **Secrets Management**: Secure handling of API keys and sensitive configuration

---

This architecture overview provides the foundation for understanding how MyStoryFlow is built and operates. For detailed implementation guides, refer to the specific sections in this documentation.