flowchart TB
    subgraph CLIENT["🖥️ CLIENT LAYER"]
        direction LR
        U(["👤 User"]) --> WEB["React + TypeScript<br/>Tailwind CSS"]
    end

    subgraph EDGE["🛡️ EDGE & GATEWAY"]
        direction LR
        CDN["CDN / Cache"] --> GW["API Gateway<br/>Rate limit · CORS · TLS"]
    end

    subgraph APP["⚙️ APPLICATION LAYER"]
        direction LR
        AUTH["Auth Service<br/>JWT · Firebase Auth"]
        CORE["Core API<br/>Laravel / Node.js"]
        AISVC["AI Service<br/>Prompt · Context · Guardrails"]
        QUEUE["Queue Worker<br/>Async jobs"]
    end

    subgraph DATA["🗄️ DATA LAYER"]
        direction LR
        PG[("PostgreSQL<br/>Relational core")]
        MG[("MongoDB<br/>Logs · Documents")]
        RD[("Redis<br/>Cache · Queue")]
        ST[("Cloud Storage<br/>Files · Assets")]
    end

    subgraph EXT["☁️ EXTERNAL & PLATFORM"]
        direction LR
        GEM["Gemini API"]
        FIR["Firebase"]
        GCP["Google Cloud<br/>Cloud Run · Logging"]
    end

    WEB -->|HTTPS| CDN
    GW --> AUTH
    GW --> CORE
    CORE --> AISVC
    CORE --> QUEUE
    AUTH --> FIR
    AISVC --> GEM
    CORE --> PG
    CORE --> RD
    QUEUE --> RD
    AISVC --> MG
    CORE --> ST
    APP -.->|deployed on| GCP

    classDef client fill:#03170c,stroke:#00ff88,color:#ffffff,stroke-width:2px
    classDef edge fill:#1a1a1a,stroke:#00ff88,color:#ffffff
    classDef app fill:#0b2a1a,stroke:#00ff88,color:#ffffff
    classDef data fill:#0d1b2a,stroke:#4285F4,color:#ffffff
    classDef ext fill:#1a1030,stroke:#8E75C2,color:#ffffff
    class U,WEB client
    class CDN,GW edge
    class AUTH,CORE,AISVC,QUEUE app
    class PG,MG,RD,ST data
    class GEM,FIR,GCP ext

sequenceDiagram
    autonumber
    actor U as 👤 User
    participant FE as 🖥️ React App
    participant GW as 🛡️ API Gateway
    participant API as ⚙️ Core API
    participant DB as 🗄️ PostgreSQL
    participant AI as 🤖 AI Service
    participant G as ✨ Gemini API

    U->>FE: Submit prompt
    FE->>GW: POST /api/ai/run (JWT)
    GW->>GW: Verify token + rate limit
    GW->>API: Forward request
    API->>DB: Load project context
    DB-->>API: Context data
    API->>AI: Build prompt + guardrails
    AI->>G: generateContent()
    G-->>AI: Model response
    AI-->>API: Sanitized result
    API->>DB: Save run + token usage
    API-->>FE: 200 OK (JSON)
    FE-->>U: Render result ✨

erDiagram
    ROLES ||--o{ USERS : "assigned to"
    USERS ||--o{ PROJECTS : owns
    USERS ||--o{ SESSIONS : opens
    USERS ||--o{ API_KEYS : issues
    USERS ||--o{ AUDIT_LOGS : generates
    PROJECTS ||--o{ TASKS : contains
    PROJECTS ||--o{ PROMPTS : defines
    PROMPTS ||--o{ AI_RUNS : executes
    USERS ||--o{ AI_RUNS : triggers

    ROLES {
        uuid id PK
        string name UK "admin | member | viewer"
        jsonb permissions
    }

    USERS {
        uuid id PK
        uuid role_id FK
        string email UK
        string password_hash
        string display_name
        boolean is_active
        timestamptz created_at
    }

    SESSIONS {
        uuid id PK
        uuid user_id FK
        string refresh_token_hash
        string ip_address
        timestamptz expires_at
    }

    API_KEYS {
        uuid id PK
        uuid user_id FK
        string key_hash UK
        string label
        timestamptz last_used_at
        timestamptz revoked_at
    }

    PROJECTS {
        uuid id PK
        uuid owner_id FK
        string name
        string slug UK
        text description
        string status "draft | active | archived"
        timestamptz created_at
    }

    TASKS {
        uuid id PK
        uuid project_id FK
        string title
        string status "todo | doing | done"
        smallint priority
        date due_date
    }

    PROMPTS {
        uuid id PK
        uuid project_id FK
        string name
        text template
        string model "gemini model id"
        int version
    }

    AI_RUNS {
        uuid id PK
        uuid prompt_id FK
        uuid user_id FK
        text input
        text output
        int tokens_in
        int tokens_out
        int latency_ms
        string status "ok | error | filtered"
        timestamptz created_at
    }

    AUDIT_LOGS {
        bigint id PK
        uuid user_id FK
        string action
        string entity
        jsonb metadata
        timestamptz created_at
    }

flowchart LR
    A["💻 Commit<br/>feature branch"] --> B["🔀 Pull Request"]
    B --> C["🧪 Lint · Test<br/>GitHub Actions"]
    C -->|pass| D["📦 Build<br/>Docker image"]
    C -.->|fail| A
    D --> E["🧭 Staging<br/>smoke test"]
    E --> F["🚀 Production<br/>Google Cloud Run"]
    F --> G["📈 Monitor<br/>Logs · Alerts"]
    G -.->|feedback| A

    classDef step fill:#0b2a1a,stroke:#00ff88,color:#ffffff
    classDef prod fill:#00ff88,stroke:#00ff88,color:#000000,font-weight:bold
    class A,B,C,D,E,G step
    class F prod