System Overview¶

The Digital Memory Chest follows a clean, modular architecture designed for both sensitivity and scalability. This overview provides a high-level understanding of how all components work together.

System Architecture¶

graph TB
    subgraph "User Interface Layer"
        UI[Streamlit Web App]
        API[Internal API Layer]
    end

    subgraph "Business Logic Layer"
        CM[Chest Manager]
        AM[Asset Manager] 
        SM[Story Manager]
        CON[Contribution Manager]
    end

    subgraph "AI Processing Pipeline"
        MP[Media Processor]
        TR[Transcription Service]
        IT[Image Tagging]
        SG[Story Generation]
    end

    subgraph "Data Layer"
        DB[(Database)]
        FS[File Storage]
        CACHE[Processing Cache]
    end

    subgraph "External Services"
        OPENAI[OpenAI API]
        ANTHROPIC[Anthropic API]
        S3[S3 Storage]
    end

    UI --> API
    API --> CM
    API --> AM
    API --> SM
    API --> CON

    AM --> MP
    MP --> TR
    MP --> IT
    SM --> SG

    TR -.->|Optional| OPENAI
    IT -.->|Local CLIP| IT
    SG -.->|LLM| OPENAI
    SG -.->|LLM| ANTHROPIC

    CM --> DB
    AM --> DB
    SM --> DB
    CON --> DB

    AM --> FS
    MP --> FS
    FS -.->|Production| S3

    MP --> CACHE

    style UI fill:#e1f5fe
    style API fill:#f3e5f5
    style DB fill:#e8f5e8
    style FS fill:#fff3e0
    style MP fill:#fce4ec

🔍 View Full Resolution

Core Principles¶

🛡️ Privacy-First Design¶

• Local Processing: AI operations can run entirely locally using Whisper and CLIP
• Token-Based Sharing: No public IDs - all sharing uses secure, revocable tokens
• Minimal PII: Only essential information stored, with soft deletes for complete removal
• Consent-Based: All contributions require explicit approval before inclusion

🔄 Async Processing Pipeline¶

• Non-Blocking Operations: Media processing happens asynchronously
• Graceful Degradation: System works even when AI services are unavailable
• Progress Tracking: Real-time feedback on processing status
• Retry Logic: Robust error handling with exponential backoff

🔌 Modular Architecture¶

• Swappable Components: Easy to change storage backends or AI providers
• Clean Interfaces: Well-defined contracts between layers
• Environment Agnostic: Works equally well in development and production
• Extensible: New features can be added without breaking existing functionality

Component Overview¶

User Interface Layer¶

• Streamlit App: Main web interface with responsive design
• Memorial-Appropriate UI: Tasteful, respectful design language
• Real-time Updates: Live progress tracking for AI operations
• Mobile Friendly: Works well on all device sizes

Business Logic Layer¶

Each manager handles a specific domain:

AI Processing Pipeline¶

sequenceDiagram
    participant U as User
    participant AM as Asset Manager
    participant MP as Media Processor
    participant TR as Transcription
    participant IT as Image Tagging
    participant DB as Database

    U->>AM: Upload Media File
    AM->>MP: Queue for Processing
    MP->>MP: Generate Thumbnail
    MP->>DB: Save Initial Metadata

    par Audio/Video Processing
        MP->>TR: Extract Audio
        TR->>TR: Transcribe (Whisper/OpenAI)
        TR->>DB: Save Transcript
    and Image Processing
        MP->>IT: Analyze Image
        IT->>IT: Generate Tags (CLIP)
        IT->>DB: Save Tags
    end

    MP->>DB: Update Processing Status
    MP->>U: Notify Completion

🔍 View Full Resolution

Data Layer¶

The data layer is built for both reliability and flexibility:

• SQLModel: Type-safe database operations with automatic validation
• Dual Database Support: SQLite for development, PostgreSQL for production
• Soft Deletes: Records are never truly deleted, preserving data integrity
• Optimistic Locking: Prevents data corruption in concurrent scenarios

External Services¶

All external dependencies are optional with local fallbacks:

• AI APIs: OpenAI and Anthropic for advanced language models
• Storage: S3-compatible storage for production deployments
• Monitoring: Optional analytics and error tracking

Deployment Patterns¶

Local Development¶

graph LR
    DEV[Developer] --> SQLITE[(SQLite)]
    DEV --> LOCAL[Local Files]
    DEV --> WHISPER[Local Whisper]
    DEV --> CLIP[Local CLIP]

Perfect for development and small-scale deployments with zero external dependencies.

Production Deployment¶

graph LR
    USERS[Users] --> LB[Load Balancer]
    LB --> APP1[App Instance 1]
    LB --> APP2[App Instance 2]
    APP1 --> PG[(PostgreSQL)]
    APP2 --> PG
    APP1 --> S3[S3 Storage]
    APP2 --> S3
    APP1 --> REDIS[Redis Cache]
    APP2 --> REDIS

Scalable architecture supporting multiple instances with shared storage and caching.

Security Architecture¶

graph TD
    subgraph "Security Layers"
        INPUT[Input Validation]
        AUTH[Token Authentication]
        AUTHZ[Authorization Checks]
        ENCRYPT[Data Encryption]
    end

    subgraph "Data Protection"
        PII[PII Minimization]
        SOFT[Soft Deletes]
        AUDIT[Audit Logging]
        BACKUP[Encrypted Backups]
    end

    subgraph "Network Security"
        TLS[TLS Encryption]
        CORS[CORS Protection]
        RATE[Rate Limiting]
        WAF[Web Application Firewall]
    end

    INPUT --> AUTH
    AUTH --> AUTHZ
    AUTHZ --> ENCRYPT
    ENCRYPT --> PII
    PII --> SOFT
    SOFT --> AUDIT
    AUDIT --> BACKUP

    TLS --> CORS
    CORS --> RATE
    RATE --> WAF

🔍 View Full Resolution