Services — 16 Canonical Microservices¶

Each service is an independently scalable process. Services communicate over gRPC (internal, with mTLS) and expose REST/WebSocket only at the API gateway edge.

External API surface: Humans and integrations call REST/WebSocket on api-gateway only, with JWT auth. Internal API: services call each other over gRPC with mTLS — no direct Postgres access across arbitrary service boundaries; each service owns its integration pattern with the DB or cache.

flowchart TB
  subgraph cp [control-plane]
    GW[api-gateway]
    ID[identity]
    AC[access-control]
  end
  subgraph kern [kernel]
    AG[agent-service]
    GL[goal-service]
    PL[planner-service]
    SCH[scheduler-service]
    TK[task-service]
    MEM[memory-service]
  end
  subgraph wrk [workers]
    LLM[llm-router]
    PM[prompt-manager]
    EV[evaluation-service]
    WM[worker-manager]
    EX[execution-worker]
    BR[browser-worker]
    TR[tool-runtime]
  end
  GW --> AG
  GW --> GL
  GL --> PL
  PL --> TK
  SCH --> EX
  EX --> TR

Service catalogue¶

Chat (v1): Chat capability is built into api-gateway. No separate chat service for Phase 10.

Optional services¶

Inter-service communication¶

External → api-gateway (REST/WebSocket)
           ↓ gRPC
           agent-service, task-service, goal-service (kernel services)
           ↓ gRPC
           llm-router, memory-service, planner-service
           ↓ stream queues
           execution-worker, browser-worker
           ↓
           tool-runtime (sandbox)

Agent lifecycle flow (summary)¶

Goal submitted → context assembled → planner builds DAG → task service persists graph → scheduler dispatches → workers run steps (including sandbox where needed) → evaluation where configured. Details: PRD §9, §15.

Chat API (Phase 10)¶

WebSocket framing: JSON types include chunk, message_start, message_end, tool_call, tool_result, done, error, pong, session. Config: CHAT_ENABLED, CHAT_MAX_MSG_LENGTH, CHAT_RATE_LIMIT, CHAT_TOKEN_CAP.

| POST | /chat/sessions/{id}/inject | External message injection (e.g., from Slack adapter) |

Dashboard API (Phase 11)¶

Dashboard served at /superadmin/dashboard/. APIs under /superadmin/api/dashboard/ and /superadmin/api/slack/.

Agent profile and documents (summary)¶

Context propagation flow:

1. goal-service receives goal with optional inline documents → persists goal-scoped documents.
2. goal-service assembles full agent context: system_prompt + rules (priority-sorted) + skills + context_docs.
3. goal-service passes assembled agent_context to planner-service.
4. planner-service embeds agent_context in each task payload.
5. execution-worker includes agent_context when building LLM prompts for task execution.

Profile and document reads served from Redis cache (agent:profile:{id}, agent:docs:{id}, 5min TTL).