Karatage Brain

flowchart LR
    OD["OneDrive\n(Source of Truth)"]
    Mirror["Local Mirror"]
    Pipeline["Pipeline\n6 Stages"]
    DB["PostgreSQL\n+ pgvector\n(The Brain)"]
    WA["WhatsApp"]
    Web["Web Console"]
    CLI["CLI"]

    OD -->|"Microsoft Graph\nDelta Sync"| Mirror
    Mirror -->|"6-stage pipeline"| Pipeline
    Pipeline --> DB
    DB --> WA
    DB --> Web
    DB --> CLI

    style OD fill:#e0effe,stroke:#0073c5,color:#064e84
    style DB fill:#f0fdf4,stroke:#16a34a,color:#166534
    style Pipeline fill:#fef9c3,stroke:#ca8a04,color:#854d0e
          

graph TB
    subgraph office["Office (Private Network)"]
        subgraph app["Application Server"]
            subgraph docker["Docker Compose"]
                pg["PostgreSQL 16\n+ pgvector\n+ pg_trgm"]
                parser["Parser\nSidecar"]
                api["API\n(FastAPI)"]
                worker["Worker\n(Procrastinate)"]
                web["Web UI\n(Next.js)"]
                waha["WAHA\n(WhatsApp)"]
            end
            mirror["OneDrive Mirror"]
            cli["brain CLI"]
        end
        ai["AI Server\n(vLLM / Ollama)\nLocal GPU inference"]
        worker --> ai
        api --> ai
    end

    onedrive["OneDrive (M365)"]
    entra["Entra IDP"]
    cf["Cloudflare Access"]
    users["Team"]

    onedrive -->|"Graph API\nDelta Queries"| mirror
    mirror --> worker
    cli --> pg
    api --> pg
    worker --> pg
    worker --> parser
    api --> parser
    web --> api
    waha --> api

    users --> cf
    cf --> entra
    cf --> web

    style pg fill:#d1fae5,stroke:#059669
    style ai fill:#fef9c3,stroke:#ca8a04
    style docker fill:#f0f9ff,stroke:#0284c7
    style app fill:#fafafa,stroke:#d4d4d4
    style office fill:#f0fdf4,stroke:#16a34a
          

flowchart TD
    mirror["OneDrive Mirror"] --> discover

    discover["DISCOVER\nSHA-256 hash = identity\nNew hash? Create row.\nKnown hash? Skip."]
    parse["PARSE\nParser sidecar: PDF, DOCX,\nXLSX, images to text chunks\nwith page locators"]
    classify["CLASSIFY\nLLM scores document against\nall known types.\nThreshold: min 0.80, margin min 0.20"]
    adjudicate["ADJUDICATE\nPair-specific LLM call\nto disambiguate"]
    extract["EXTRACT\nPer-type structured extraction\nLLM to Pydantic model to JSON\nwith per-field confidence"]
    resolve["RESOLVE\nMap names/IDs to canonical\ndatabase entities.\nAmbiguous = proposal"]
    apply["APPLY\nStratified fixpoint loop.\nPreconditions + effects.\nLoop until convergence."]
    unknown["UNKNOWN\nOperator triage queue"]

    discover --> parse --> classify
    classify -->|"Confident"| extract
    classify -->|"Below threshold"| unknown
    classify -->|"Margin too narrow"| adjudicate
    adjudicate -->|"Resolved"| extract
    adjudicate -->|"Still unclear"| unknown
    extract --> resolve --> apply

    style discover fill:#e0effe,stroke:#0073c5
    style parse fill:#e0effe,stroke:#0073c5
    style classify fill:#fef9c3,stroke:#ca8a04
    style adjudicate fill:#fef3c7,stroke:#d97706
    style extract fill:#d1fae5,stroke:#059669
    style resolve fill:#d1fae5,stroke:#059669
    style apply fill:#d1fae5,stroke:#059669
    style unknown fill:#fee2e2,stroke:#dc2626
          

sequenceDiagram
    participant Op as Operator
    participant CLI as brain CLI
    participant Graph as Microsoft Graph API
    participant Mirror as Local Mirror
    participant DB as PostgreSQL
    participant Pipeline as Pipeline

    Op->>CLI: brain sync
    CLI->>DB: Load delta token
    DB-->>CLI: token (or null for first sync)

    alt First sync (no token)
        CLI->>Graph: GET /delta (full tree)
        Graph-->>CLI: All files + deltaLink
    else Incremental sync
        CLI->>Graph: GET {deltaLink}
        Graph-->>CLI: Changed files + new deltaLink
    end

    loop Each changed file
        CLI->>Graph: Download file
        Graph-->>CLI: File bytes
        CLI->>Mirror: Write to mirror/
    end

    CLI->>DB: Store new delta token
    CLI->>Pipeline: Trigger ingestion on changed files
    Pipeline->>DB: discover, parse, classify, ...
          

erDiagram
    FUND ||--o{ INVESTMENT : "invests via"
    DEAL ||--o{ INVESTMENT : "facilitates"
    COMPANY ||--o{ INVESTMENT : "receives"

    FUND {
        uuid id PK
        string name
        int vintage_year
        numeric fund_size
        string status
    }

    DEAL ||--o{ DEAL_PARTY : "involves"
    DEAL ||--o{ DEAL_MILESTONE : "tracks"
    DEAL ||--o{ CONTRACT : "has"
    DEAL ||--o{ DD_ITEM : "requires"
    DEAL }o--|| COMPANY : "targets"

    DEAL {
        uuid id PK
        string name
        string deal_type
        string status
        numeric deal_value
        date signed_on
    }

    COMPANY ||--o{ FINANCIAL_DATA : "reports"
    COMPANY ||--o{ DEAL_PARTY : "participates"
    CONTACT ||--o{ DEAL_PARTY : "participates"
    CONTACT }o--o| COMPANY : "works at"

    COMPANY {
        uuid id PK
        string name
        string registration_number
        string country
        string industry
    }

    CONTACT {
        uuid id PK
        string full_name
        string email
        string phone
        string role_type
    }
          

flowchart TD
    subgraph R1["Round 1"]
        ts1["Term Sheet\nPrecondition: none\nCreates Deal 'Acme'\nCreates Company 'Acme Corp'"]
        br1["Board Resolution\nPrecondition: Deal exists\nDeal doesn't exist yet\nStatus: PENDING"]
    end

    subgraph R2["Round 2"]
        br2["Board Resolution\nPrecondition: Deal exists\nDeal now exists!\nCreates Milestone 'board_approval'"]
    end

    subgraph R3["Round 3"]
        conv["No changes = CONVERGED"]
    end

    R1 --> R2 --> R3

    style ts1 fill:#d1fae5,stroke:#059669
    style br1 fill:#fef3c7,stroke:#d97706
    style br2 fill:#d1fae5,stroke:#059669
    style conv fill:#e0effe,stroke:#0073c5
          

sequenceDiagram
    participant U as User (WhatsApp/Web)
    participant P as Phase 1: PLANNER
    participant D as Phase 2: DISPATCH
    participant S as Phase 3: SYNTHESIZER

    U->>P: "What's the status of the Acme deal?"

    Note over P: LLM call #1 (JSON mode)
    P->>P: Maps to tool: deal_status
    P->>P: Params: {kind: "deal", name: "Acme"}

    P->>D: {intent, tool, params}

    Note over D: Deterministic code (no LLM)
    D->>D: Resolve "Acme" → Deal ID
    D->>D: Run deal_status tool → structured data
    D->>D: Retrieve top-k chunks (vector + lexical)

    D->>S: tool_results + retrieved_chunks

    Note over S: LLM call #2 (plain text)
    S->>S: Write grounded answer
    S->>S: Cite only provided documents

    S->>U: "The Acme acquisition is in due diligence.\nTerm sheet signed 2026-03-15 for R50M.\n[doc:a1b2c3]"
          

sequenceDiagram
    participant WA as WhatsApp User
    participant WAHA as WAHA Gateway
    participant API as Brain API
    participant RAG as RAG Agent
    participant DB as PostgreSQL

    WA->>WAHA: Send message
    WAHA->>API: POST /whatsapp/webhook (HMAC-SHA512)
    API->>API: Verify HMAC signature
    API->>DB: Resolve sender → known contact
    API->>DB: Check wa_operators allowlist

    alt Authorized operator
        API->>RAG: Process question
        RAG->>DB: Plan → Dispatch → Retrieve
        RAG-->>API: Grounded answer + citations
        API->>WAHA: Send reply
        WAHA->>WA: Deliver answer
    else Unknown sender
        API->>DB: Store message (no answer)
    end
          

flowchart LR
    U["Team Members"]
    CF["Cloudflare Access"]
    E["Entra IDP\n(Azure AD)"]
    JWT["JWT Token"]
    API["Brain API"]
    WA["WhatsApp"]
    HMAC["HMAC-SHA512\nVerification"]

    U -->|"Web / API"| CF
    CF --> E
    E --> JWT
    JWT --> API
    WA -->|"Webhook"| HMAC
    HMAC --> API

    style CF fill:#f0f9ff,stroke:#0284c7
    style E fill:#e0effe,stroke:#0073c5
          

flowchart LR
    subgraph office["Office Private Network"]
        app["Brain\n(Application Server)"]
        ai["AI Server\n(GPU)"]
        app -->|"classify / extract\n/ embed / OCR"| ai
        ai -->|"structured output"| app
    end

    internet["Public Internet"]
    app -.->|"OneDrive sync only\n(file download)"| internet

    style office fill:#f0fdf4,stroke:#16a34a
    style ai fill:#fef9c3,stroke:#ca8a04
    style internet fill:#fee2e2,stroke:#dc2626