flowchart TB
    subgraph Clients
        UA[CLI / curl / SDK]
        BR[Browser / Passkey]
    end

    subgraph Edge["pkg/web — HTTP + WebSocket"]
        direction TB
        MW[chi router + middleware<br/>RequestID · Recovery · Log<br/>OTel · JWT Auth · RBAC · RateLimit]
        SSE[/v1/ask/stream SSE/]
        WS[/v1/chat/ws WebSocket/]
        OAUTH[/v1/oauth · /v1/webauthn/]
        MCPEP[/mcp JSON-RPC/]
    end

    subgraph Platform["MARA platform"]
        ORCH[pkg/orchestration]
        BUS[pkg/comm Bus]
        REG[pkg/registry]
        POL[pkg/governance Composite Policy]
        AGENTS[(60+ specialist agents)]
        FB[Fallback agents]
        ORCH --> BUS
        ORCH --> POL
        REG --> ORCH
        BUS --> AGENTS
        AGENTS --> FB
    end

    subgraph AI["GenAI layer"]
        LLM[pkg/llm<br/>Mock · Ollama · Anthropic<br/>OpenAI · Gemini]
        RAG[pkg/rag<br/>hybrid · pgvector · rerank<br/>Self-RAG · CRAG]
        GRAG[pkg/graphrag<br/>entity graph]
        REAS[pkg/reasoning<br/>CoT · ReAct · Reflexion<br/>CoV · Step-Back]
        MEM[pkg/memory<br/>semantic + episodic]
        CONST[pkg/constitution<br/>7 Sutras]
        TOOL[pkg/toolkit · pkg/eval]
        SAFE[pkg/safety]
    end

    subgraph Data
        PG[(Postgres<br/>users · documents · incidents<br/>consents · mcp_tokens · pgvector)]
        VAULT[(Encrypted at rest<br/>pkg/crypto envelope)]
    end

    subgraph Observability
        OTLP[OTel Collector]
        TEMPO[(Tempo)]
        GRAF[Grafana]
        OTLP --> TEMPO --> GRAF
    end

    subgraph External
        KITE[Zerodha Kite MCP]
        AA[Sahamati AA]
        OLLAMA[Ollama runtime]
    end

    UA -->|REST + Bearer JWT| MW
    BR -->|Passkey| OAUTH
    MW --> SSE
    MW --> WS
    MW -->|Publish| BUS
    AGENTS --> LLM
    AGENTS --> RAG
    AGENTS --> GRAG
    AGENTS --> MEM
    LLM --> OLLAMA
    AGENTS --> KITE
    AGENTS --> AA
    AGENTS --> PG
    PG --> VAULT
    AGENTS --> OTLP
    MW --> OTLP
    LLM --> OTLP
    POL -.audit.-> AGENTS
    REAS -.via.-> LLM
    SAFE -.via.-> POL
    TOOL -.via.-> POL
    CONST -.via.-> POL

flowchart TB
    SUP[financial_supervisor]
    HSUP[h_supervisor<br/>semantic router]
    ING[ingestor]
    NORM[normalizer]
    ENR[enricher]
    AN[analyzer]
    FC[forecaster]
    AD[anomaly_detector]
    REC[recommender]
    MOA[moa_recommender<br/>Mixture-of-Agents]
    REP[reporter]
    OCR[receipt_ocr<br/>vision]

    CUR[currency_converter]
    EDU[financial_educator<br/>+RAG citations]
    MAC[macro_research]
    RAT[rate_watcher]
    LOA[loan_advisor]
    TAX[tax_estimator<br/>FY 2024-25]
    AUD[llm_auditor<br/>LLM-as-judge]

    PA[portfolio_advisor<br/>Zerodha Kite MCP]
    AAF[aa_fetcher<br/>Sahamati AA]
    VO[voice<br/>Bhashini-shaped]

    FB[fallback agents]

    HSUP -.routes.-> SUP
    HSUP -.routes.-> TAX
    HSUP -.routes.-> PA

    OCR -->|raw_transactions| NORM
    SUP -->|kicks off| ING --> NORM --> ENR --> AN
    AN --> FC --> SUP
    AN --> AD --> SUP
    AN --> REC --> SUP
    AN --> SUP
    SUP --> REP
    AAF --> SUP

    AUD -. "broadcast subscriber" .-> SUP
    REC -. fail .-> FB

    classDef adk fill:#fef6dd,stroke:#d99e2c
    classDef india fill:#dffce9,stroke:#249e57
    classDef vision fill:#e7e3ff,stroke:#5b3eb1
    class CUR,EDU,MAC,RAT,LOA,AUD adk
    class PA,AAF,VO,TAX india
    class OCR vision

sequenceDiagram
    autonumber
    actor U as User
    participant API as cmd/api
    participant DB as Postgres
    participant ENC as pkg/crypto
    participant BUS as comm.Bus
    participant POL as Governance Composite
    participant SUP as supervisor
    participant ING as ingestor
    participant N as normalizer
    participant EN as enricher
    participant AN as analyzer
    participant FC as forecaster
    participant AD as anomaly
    participant REC as recommender
    participant REP as reporter
    participant AUDIT as llm_auditor

    U->>API: POST /v1/users/login
    API->>DB: SELECT user
    API->>U: 200 {token}

    U->>API: POST /v1/documents (CSV body, JWT)
    API->>ENC: Encrypt(csv)
    API->>DB: INSERT documents (envelope JSONB)
    API->>U: 201 {id, classification, kek_id}

    U->>API: POST /v1/ask {question, document_id}
    API->>DB: SELECT documents WHERE id=?
    API->>ENC: Decrypt(payload)
    API->>BUS: Publish finance_question

    BUS->>POL: Evaluate (length, RBAC, classification,<br/>residency, consent, PII, injection, schema)
    POL-->>BUS: allow
    BUS->>SUP: HandleMessage
    SUP->>BUS: ingest_csv → ingestor

    BUS->>ING: HandleMessage
    ING->>BUS: raw_transactions
    BUS->>N: HandleMessage
    N->>BUS: normalized_transactions
    BUS->>EN: HandleMessage
    EN->>BUS: enriched_transactions

    BUS->>AN: HandleMessage
    par
        AN->>BUS: → forecaster
    and
        AN->>BUS: → anomaly_detector
    and
        AN->>BUS: → recommender
    and
        AN->>BUS: → supervisor (snapshot)
    end

    BUS->>FC: HandleMessage
    FC->>BUS: forecast_result → supervisor
    BUS->>AD: HandleMessage
    AD->>BUS: anomalies → supervisor
    BUS->>REC: HandleMessage
    REC->>BUS: recommendations → supervisor

    BUS->>SUP: 4 fan-ins collected
    SUP->>BUS: final_report_request → reporter
    BUS->>REP: HandleMessage
    REP->>BUS: final_report → user
    BUS-->>API: Correlator wakes the waiting handler
    API->>U: 200 {trace_id, report, ai_disclosure}

    AUDIT-->>BUS: (broadcast) scores every message<br/>against constitution

sequenceDiagram
    actor U as User
    participant API as cmd/api
    participant Repo as UserRepo (Postgres)
    participant JWT as auth.Issuer (HS256)
    participant Bus
    participant POL as RBACPolicy
    participant AG as agent

    Note over U,Repo: Signup / Login
    U->>API: POST /v1/users {email,name,password}
    API->>API: bcrypt(password)
    API->>Repo: INSERT users
    API->>JWT: Issue(subject, email, [user])
    API->>U: {token, expires_at}

    Note over U,AG: Subsequent calls
    U->>API: GET /v1/users/me<br/>Authorization: Bearer <token>
    API->>JWT: Verify(token)
    JWT-->>API: claims{sub, roles, exp}

    U->>API: POST /v1/ask
    API->>Bus: Publish (user_roles in metadata)
    Bus->>POL: Evaluate
    POL-->>Bus: allow (role satisfied)
    Bus->>AG: HandleMessage

flowchart LR
    PT[CSV plaintext]
    DEK[(DEK 32 bytes,<br/>fresh per doc)]
    KEK[(KEK<br/>env / KMS)]
    CT[ciphertext]
    WDEK[wrapped DEK]
    JSON[EncryptedPayload<br/>kek_id · wrapped_dek<br/>nonce · ciphertext]

    PT --AES-256-GCM--> CT
    DEK --AES-256-GCM--> WDEK
    KEK -.wraps.-> DEK
    CT --> JSON
    WDEK --> JSON
    JSON --> PG[(documents.payload JSONB)]

flowchart TB
    MSG[Message] --> C[governance.CompositePolicy]
    C --> P1[MaxContentLengthPolicy]
    C --> P2[RequiredMetadataPolicy<br/>trace_id, user_id]
    C --> P3[RBACPolicy<br/>roles vs message type]
    C --> P4[ClassificationPolicy<br/>recipient ceiling]
    C --> P5[DataResidencyPolicy<br/>region tags]
    C --> P6[ConsentPolicy<br/>type → category]
    C --> P7[ExplainabilityPolicy<br/>requires rationale]
    C --> P8[PIIBlockPolicy<br/>regex]
    C --> P9[PromptInjectionPolicy<br/>known markers]
    C --> P10[SchemaPolicy<br/>JSON schema]
    P1 & P2 & P3 & P4 & P5 & P6 & P7 & P8 & P9 & P10 --> D{any deny?}
    D -- yes --> SP[span.Error<br/>denials counter<br/>auto-incident<br/>msg dropped]
    D -- no --> A[agent.HandleMessage]

flowchart LR
    APP[genie-api / cmd/genie] --OTLP gRPC--> COL[otel-collector]
    COL --> TEMPO[(Tempo)]
    APP --slog JSON--> STDOUT[(stdout / Loki)]
    TEMPO --datasource--> GRAF[Grafana]

    APP -.OpenInference attrs.-> PHX[(Arize Phoenix<br/>Langfuse)]

sequenceDiagram
    actor U as User
    participant API as cmd/api
    participant OCR as receipt_ocr
    participant VIS as Vision Provider<br/>Ollama llava
    participant NORM as normalizer
    participant SUP as supervisor

    U->>API: POST /v1/documents (image/jpeg)
    API->>OCR: receipt_ocr_request<br/>base64 image
    OCR->>VIS: Complete + ImagePart
    VIS-->>OCR: JSON {date, merchant, amount_cents, ...}
    OCR->>NORM: raw_transactions<br/>(classification=pii)
    NORM->>SUP: normalized → ... → final_report

flowchart TB
    Q[User query]
    Q --> SR{Self-RAG<br/>need retrieval?}
    SR -- no --> ANS[Direct answer]
    SR -- yes --> QR[Query rewrite<br/>HyDE optional]
    QR --> VEC[Vector search<br/>pgvector / in-mem]
    QR --> BM25[BM25 keyword search]
    VEC --> RRF[Reciprocal Rank Fusion]
    BM25 --> RRF
    RRF --> RR[Cross-encoder rerank<br/>LLMReranker]
    RR --> CRAG{CRAG grade<br/>per-chunk relevance}
    CRAG --> KEEP[Kept chunks]
    CRAG --> DROP[Dropped]
    KEEP --> REORDER[Lost-in-middle reorder]
    REORDER --> CTX[Final context]
    CTX --> LLM[LLM call]
    LLM --> OUT[Answer + citations]

flowchart LR
    U[(User<br/>alice)]
    A[(Account<br/>acct-1)]
    T1[(Transaction<br/>txn-1)]
    T2[(Transaction<br/>txn-2)]
    M1[(Merchant<br/>swiggy)]
    M2[(Merchant<br/>rent)]
    C1[(Category<br/>food:delivery)]
    C2[(Category<br/>housing:rent)]

    U --OWNS--> A
    A --HAS_TXN--> T1
    A --HAS_TXN--> T2
    T1 --PAID_TO--> M1
    T2 --PAID_TO--> M2
    T1 --CATEGORISED_AS--> C1
    T2 --CATEGORISED_AS--> C2

flowchart LR
    subgraph PerUser[per-user memory layers]
        ST[Short-term<br/>conversation buffer]
        EM[Episodic<br/>chronological + summary]
        LT[Long-term semantic<br/>vector store]
    end

    Q[Query] --> ST
    Q --> EM
    Q --> LT
    ST --> PR[Prompt context]
    EM --> PR
    LT --> PR
    PR --> LLM

    EM -. consolidate .-> SUMM[LLM Summariser]
    SUMM --> EM

flowchart LR
    OUT[Agent output] --> J[LLM-as-judge<br/>constitution.Critique]
    OUT --> RAGAS[ragas.Evaluator<br/>faithfulness · relevance<br/>context precision]
    OUT --> HAL[hallucination.Detect<br/>per-sentence labels]
    OUT --> CHK[checklist.Run<br/>behavioral suite]
    OUT --> DRIFT[drift.KL<br/>output distribution]
    OUT --> ELO[elo.Ratings<br/>pairwise]
    J & RAGAS & HAL & CHK & DRIFT & ELO --> STORE[(eval.Store)]

flowchart TB
    START[Run] --> A[Step A<br/>load CSV]
    A -->|completed| B[Step B<br/>compute analysis]
    B --> C{Step C<br/>RequireApproval}
    C -.awaiting.-> APR[POST /v1/approvals]
    APR --> CRUN[Step C runs<br/>commit decision]
    CRUN -->|completed| D[Step D<br/>notify user]

    A -. fail .-> X{Failure}
    B -. fail .-> X
    C -. fail .-> X
    D -. fail .-> X
    X --> COMP[Run compensations<br/>in reverse]

sequenceDiagram
    actor U as User
    participant API as cmd/api
    participant DB as Postgres mcp_tokens
    participant ADV as portfolio_advisor
    participant KITE as mcp.kite.trade

    U->>API: POST /v1/mcp/tokens<br/>{provider, endpoint, token}
    API->>DB: encrypt(token) → mcp_tokens
    Note over U: Later, in /v1/ask
    API->>ADV: bus → portfolio_request
    ADV->>DB: SELECT mcp_tokens
    ADV->>API: Decrypt(payload) → bearer
    ADV->>KITE: initialize<br/>tools/call get_holdings<br/>tools/call get_positions
    KITE-->>ADV: snapshot
    ADV->>API: portfolio_snapshot (classification=pii)

sequenceDiagram
    participant G1 as Genie A
    participant G2 as Genie B<br/>(remote agent)

    G1->>G2: agent/getCard
    G2-->>G1: AgentCard{skills: [...]}
    G1->>G2: task/submit {skill_id, input}
    G2-->>G1: TaskResult{status: completed, output}

sequenceDiagram
    actor U as User
    participant CLI as Genie Client
    participant IDP as Zerodha (or any IdP)

    CLI->>IDP: device_authorization
    IDP-->>CLI: device_code · user_code "WDJF-K9X3"<br/>verification_uri · interval 5s
    CLI->>U: "Visit <uri> and enter WDJF-K9X3"
    U->>IDP: opens uri, types code, logs in
    loop every interval seconds
        CLI->>IDP: token?
        IDP-->>CLI: authorization_pending
    end
    Note over IDP: user approves
    CLI->>IDP: token?
    IDP-->>CLI: {access_token, token_type, expires_in}
    CLI->>CLI: store token (encrypted)

sequenceDiagram
    actor U as User
    participant BR as Browser
    participant API as cmd/api
    participant WA as webauthn.Service
    participant JWT as auth.Issuer

    Note over U,BR: First-time registration
    BR->>API: POST /v1/webauthn/register/begin
    API->>WA: BeginRegistration(userID)
    WA-->>API: ceremonyID, challenge
    API->>BR: challenge
    BR->>BR: navigator.credentials.create()
    BR->>API: credentialID, publicKey
    API->>WA: FinishRegistration(...)

    Note over U,BR: Later — passwordless login
    BR->>API: POST /v1/webauthn/login/begin
    API->>WA: BeginAssertion(userID)
    WA-->>API: challenge
    BR->>BR: navigator.credentials.get()<br/>signs challenge with passkey
    BR->>API: signature
    API->>WA: FinishAssertion(...)<br/>verifies ed25519
    API->>JWT: Issue token
    API->>BR: {access_token}

flowchart LR
    MSG[Message<br/>region=us<br/>classification=pii] --> POL{DataResidencyPolicy<br/>HomeRegion=in}
    POL -- deny --> X[Span error<br/>denials counter<br/>auto-incident]
    OK[Message<br/>region=on-prem<br/>classification=secret] --> POL2{DataResidencyPolicy}
    POL2 -- allow --> AGENT[on-prem agent]

    PII[PII request] --> ROUTE{Router}
    ROUTE --> LOCAL[Ollama on-prem<br/>region=on-prem]
    PUBLIC[Public request] --> ROUTE
    ROUTE --> REMOTE[Anthropic / Gemini / OpenAI<br/>region=us]

sequenceDiagram
    participant W1 as Worker 1
    participant W2 as Worker 2
    participant W3 as Worker 3
    participant AGG as Aggregator

    Note over W1,W3: Each worker has local data, never leaves
    W1->>W1: SplitAdditiveShares(value, 3, P)
    W2->>W2: SplitAdditiveShares(value, 3, P)
    W3->>W3: SplitAdditiveShares(value, 3, P)

    par
        W1->>W2: share_1,2
        W1->>W3: share_1,3
    and
        W2->>W1: share_2,1
        W2->>W3: share_2,3
    and
        W3->>W1: share_3,1
        W3->>W2: share_3,2
    end

    W1->>AGG: sum of received shares
    W2->>AGG: sum of received shares
    W3->>AGG: sum of received shares
    AGG->>AGG: Reveal() → aggregated sum
    Note over AGG: never sees individual values

flowchart LR
    REG[registry.List] --> MAN[Manifest per agent<br/>id · kind · model · region<br/>training_data_class · risk_class]
    EXT[Builder.Add for LLMs / embedders / tools] --> MAN
    MAN --> DOC[Document<br/>generated_at + components]
    DOC --> CDX[CycloneDX 1.6 ML-BOM]
    DOC --> SIG[Sign with Ed25519]
    SIG --> OUT[SignedDocument]
    OUT --> CONS[Regulator / auditor]

flowchart LR
    BUS[protocol.Message] --Wrap--> CE[CloudEvents 1.0<br/>specversion · id · source<br/>type=com.c2siorg.genie.*<br/>genieclassification · genietraceid]
    CE --> EXT[Kafka / NATS / Knative consumers]
    BUS -.described by.-> ASYNC[docs/asyncapi.yaml]
    SPAN[OTel LLM span] -.semconv.-> OINF[OpenInference / OpenLLMetry<br/>Arize Phoenix · Langfuse]

flowchart LR
    BR[Browser] --> ROOT[GET /]
    ROOT -- 302 --> UI[/ui/]
    UI --> APP[index.html + styles.css + app.js]
    APP -->|fetch /v1/*| API[Genie HTTP API]
    APP -->|fetch + ReadableStream| SSE[/v1/ask/stream/]
    APP -. shows .-> EVT[Agent pipeline events]
    APP -. shows .-> REPORT[Final report]