System architecture

flowchart LR
  subgraph External
    TG["Telegram<br/>@happ_soma_bot"]
    GPS["Google Pub/Sub<br/>(gmail)"]
    INN["Inngest Cloud<br/>(cron + events)"]
  end

  subgraph Vercel["Vercel · soma-ai.cc"]
    direction TB
    Pages["RSC pages /app/*"]
    Chat["/api/chat"]
    InngestR["/api/inngest"]
    Bot["/api/telegram/webhook"]
    Gmail["/api/webhooks/gmail"]
    Mastra["Mastra agent<br/>@soma/agent"]
    Tools["@soma/tools"]
  end

  subgraph Services
    SB[("Supabase<br/>Postgres + pgvector<br/>Auth")]
    LLM["Anthropic<br/>Claude 4.5"]
    Voy["Voyage AI<br/>embed + rerank"]
    GG["Google APIs<br/>Gmail + Calendar"]
  end

  subgraph Observability
    Lf["Langfuse"]
    Sn["Sentry"]
    Ph["PostHog"]
    Ax["Axiom"]
  end

  TG --> Bot
  GPS --> Gmail
  INN --> InngestR
  Bot --> Mastra
  Chat --> Mastra
  InngestR --> Tools
  Gmail -.->|fire event| INN
  Mastra --> Tools
  Mastra --> LLM
  Tools --> Voy
  Tools --> SB
  Tools --> GG
  Pages --> SB
  Mastra -.-> Lf
  Vercel -.-> Sn
  Pages -.-> Ph
  Vercel -.-> Ax

sequenceDiagram
  participant U as User
  participant Web as apps/web /api/chat
  participant Agent as somaAgent (Mastra)
  participant Claude
  participant Tools as @soma/tools
  participant PG as Postgres + pgvector
  participant Lf as Langfuse

  U->>Web: POST message
  Web->>Lf: startTrace(web.chat)
  Web->>Agent: stream(messages)
  Agent->>Claude: completion with tool schemas
  Claude-->>Agent: tool_call memory_recall(query)
  Agent->>Tools: memory_recall.execute(query)
  Tools->>Tools: embed(query) via Voyage
  Tools->>PG: SELECT ... ORDER BY embedding cosine
  PG-->>Tools: top-N candidates (3x)
  Tools->>Tools: rerank via Voyage rerank-2
  Tools-->>Agent: top-K reranked
  Agent->>Claude: continuation with context
  Claude-->>Agent: final text
  Agent-->>Web: streaming chunks
  Web-->>U: SSE tokens
  Web->>Lf: trace.end and flush