graph TD
    subgraph Client["CLIENT LAYER"]
        FL["Flutter app\nProvider · Firebase SDK\nHome · Calendar · Dashboard · Profile"]
    end

    subgraph Auth["AUTHENTICATION & DATA"]
        FA["Firebase Auth\nEmail / Password"]
        FS["Cloud Firestore\nUsers · Tasks · Schedules · Metrics"]
    end

    subgraph Gateway["API GATEWAY"]
        API["FastAPI on Cloud Run\nCORS · Token validation · BackgroundTasks\nAI response validation · Error standardization"]
    end

    subgraph Gemma["GEMMA 4 MODELS VIA OPENROUTER"]
        G31["Gemma 4 31B Dense\n─────────────────\nTask planning\nTime estimation\nPhase generation\nNotion doc generation"]
        G2["Gemma 4 2B\n─────────────────\nMorning replan\nSchedule redistribution\nMicrotask adjustments"]
        G26["Gemma 4 26B MoE\n─────────────────\nMermaid flowcharts\nExcalidraw diagrams\nMulti-domain analysis"]
    end

    subgraph NotionPkg["NOTION INTEGRATION — notion/ PACKAGE"]
        NP["pages.py — Page creation"]
        ND["databases.py — Progress tracker"]
        NF["formatting.py — Rich text"]
        NO["oauth.py — OAuth flow"]
        NS["sync.py — Status syncing"]
    end

    subgraph External["EXTERNAL SERVICES"]
        TF["TinyFish API\nWeb resource scraping\nExcalidraw automation"]
        EX["Excalidraw\nWorkflow diagrams\nCollaboration rooms"]
    end

    subgraph Execution["EXECUTION LAYER"]
        CR["Cursor Agent\nReads Notion via MCP\nExecutes phases as code\nUpdates progress tracker"]
    end

    FL -->|"HTTPS + Bearer token"| API
    FL -->|"Sign in / Sign up"| FA
    FL -->|"Real-time sync"| FS
    API -->|"Read / Write"| FS
    API -->|"Deep reasoning"| G31
    API -->|"Fast replan"| G2
    API -->|"Diagram synthesis"| G26
    API --> NP
    API --> ND
    API --> NS
    API -->|"Scrape resources"| TF
    TF -->|"Render Mermaid"| EX
    CR -->|"Read phases"| NP
    CR -->|"Update status"| NS

    style Client fill:#e8e6f9,stroke:#534AB7,color:#26215C
    style Auth fill:#e1f5ee,stroke:#0F6E56,color:#04342C
    style Gateway fill:#e6f1fb,stroke:#185FA5,color:#042C53
    style Gemma fill:#f1efe8,stroke:#5F5E5A,color:#2C2C2A
    style NotionPkg fill:#f1efe8,stroke:#5F5E5A,color:#2C2C2A
    style External fill:#eaf3de,stroke:#3B6D11,color:#173404
    style Execution fill:#fbeaf0,stroke:#993556,color:#4B1528

sequenceDiagram
    participant U as User
    participant FL as Flutter app
    participant API as FastAPI
    participant G31 as Gemma 31B Dense
    participant G2 as Gemma 2B
    participant G26 as Gemma 26B MoE
    participant FS as Firestore
    participant NT as Notion
    participant TF as TinyFish
    participant EX as Excalidraw
    participant CR as Cursor Agent

    U->>FL: Create task (title, category, deadline)
    FL->>API: POST /plan-task
    API->>G31: Send planning prompt
    Note over G31: Reasons through complexity<br/>Estimates total time<br/>Generates phases + microtasks<br/>Distributes across calendar<br/>Calculates pressure and risk
    G31-->>API: Structured JSON plan
    API->>API: _validate_ai_plan()
    API->>FS: Store validated plan + metrics
    FS-->>FL: Real-time update — calendar populates

    par Notion workspace generation
        API->>G31: Generate page content
        G31-->>API: Structured sections
        API->>NT: Create Let's Get Started page
        API->>NT: Create Progress Tracker database
        API->>NT: Add phase notes with microtasks
    and Web resource scraping
        API->>TF: Scrape resources for task topic
        TF-->>API: Curated links
        API->>NT: Add resources section to page
    and Workflow diagram generation
        API->>G26: Generate Mermaid flowchart from phases
        G26-->>API: Mermaid code
        API->>TF: Open Excalidraw and import Mermaid
        TF->>EX: Render diagram and start collab room
        EX-->>API: Collaboration room URL
        API->>NT: Add workflow diagram link to page
    end

    Note over NT: Notion workspace complete

    Note over CR: User triggers execution in Cursor
    CR->>NT: Search for latest task page
    CR->>NT: Read Progress Tracker and extract phases
    CR->>NT: Read Notes and extract microtasks
    CR->>CR: Execute Phase 1 as code
    CR->>NT: Update Phase 1 status to Done
    CR->>CR: Execute Phase 2 as code
    CR->>NT: Update Phase 2 status to Done

    Note over FL: Next morning user opens app
    FL->>API: Check yesterday completions
    API->>G2: Redistribute missed tasks
    Note over G2: Fast under 2 seconds<br/>Moves missed microtasks<br/>Rebalances remaining days
    G2-->>API: Adjusted schedule
    API->>FS: Update schedule and recalculate metrics
    FS-->>FL: Calendar and meters refresh