digikedai-bot/docs/ARCHITECTURE.md

Architecture

Multi-channel AI messaging platform. Telegram is the first adapter, not the definition of the system.

Layering

        CHANNEL LAYER
   +-------+-------+-------+
   |Telegram|Shopee |Lazada|
   |adapter |adapter|adapter|
   +-------+-------+-------+
              |
        APPLICATION CORE          (channel-agnostic message contract)
              |
     +--------+--------+
     |        |        |
  AI/Agent  n8n Tools  (integrations)
     |        |
  Memory  PostgreSQL
     |        |
  pgvector   (Phase 3)
     |
  LLM APIs (LiteLLM → OpenAI/OpenRouter)

Responsibilities

Layer	Owns	Must NOT own
Channel adapter (src/channels/*)	Native event parsing, platform formatting/IDs, buttons, webhook setup	Business rules, prompt construction, DB schema
Application core (src/core)	Normalized message contract, capabilities flags	Telegram-only assumptions
AI layer (src/ai)	Prompt assembly, agent orchestration, memory/retrieval interfaces	Platform transport
DB (src/db)	Users, conversations, messages, migration	Transient in-process state
n8n (src/integrations/n8n)	Automation/tool calls with schema validation	Core conversational state

Data flow (one message)

1. Telegram POST → Hono webhook POST /webhook/<secret>.
2. grammY parses the update → normalizeIncoming() → IncomingMessage.
3. db.saveExchange() upserts user, opens/reuses conversation, stores the user message.
4. Agent.respond() builds system+business prompt (plus user-memory block when a summary exists), fetches recent history, calls LLM.
5. Reply persisted via saveExchange() (assistant role), returned to grammY → Telegram.
6. Agent.updateMemoryAsync() (fire-and-forget, never blocks the reply) writes lang + last_queries (FIFO-5) rule-based, and triggers the MemoSummarizer (cheap chatSmall call) when new facts appear → updated summary back into user_memory.

Key contracts

• IncomingMessage / OutgoingMessage (src/core/messages.ts) — the single normalized shape every adapter translates to/from.
• ChannelCapabilities — flags (supportsButtons, etc.) so the core never assumes a feature exists on every channel.
• Provider/retriever/memory interfaces — defined now, no-op until justified (Phases 2/3).

Networking

• The bot container joins the existing mem0_net (external) to reach mem0-postgres and litellm by container name.
• Production webhook must be HTTPS: bot.digikedai.com via the DSM CF-tunnel → Traefik → this container (routing added in a later step; see docs/OPERATIONS.md).
• PostgreSQL is never exposed publicly.