APIs Architecture

The Three Backends

GoGrab runs three core backends. Each has ONE job. No overlap.

A fourth backend (backend-docs-api, port 3002) handles documentation. It's independent and not covered here.

backend-api (3000) — "The Database"

What belongs here: Any data that platform web apps read/write. Users, spaces, universes, modules, widgets, properties, themes, billing, deployment pipeline, git provider abstraction, admin.

What does NOT belong here: AI reasoning, tool execution, agent logic, LLM calls.

Key rule: This is the source of truth for all platform entities. Other backends call it to read/write platform data, never the reverse.

Domains

Databases

Calls no other backend. Is called by everyone.

backend-ai-api (3001) — "The Brain"

What belongs here: Intelligence. Anything that helps the system learn, decide, remember patterns, or expose AI tools via MCP.

What does NOT belong here: Tool execution, sandbox management, browser automation, code generation pipeline. (These belong in vitto-api — see consolidation note below.)

Domains (target state)

Databases

Calls

Current state vs target

NOTE: As of March 2026, backend-ai-api also contains ~17 controllers that belong in backend-vitto-api: sandbox proxy, browser/desktop/computer-use automation, git proxy, code generation workflow, orchestration relay, observatory, skills, task runner. A consolidation is planned — see docs/superpowers/specs/2026-03-24-backend-consolidation-design.md. Until that migration happens, these controllers remain functional in ai-api.

backend-vitto-api (3003) — "The Hands"

What belongs here: Execution. Anything that DOES something — runs tools, manages sandboxes, browses the web, generates code, talks to users via channels, proxies git operations.

What does NOT belong here: Pattern learning, decision storage, MCP protocol, agent registry.

Domains

Databases

Calls

Data Flow Direction

                    ┌──────────────┐
                    │  backend-api │
                    │   (3000)     │
                    │ "The Database"│
                    └──────┬───────┘
                           │
              reads/writes platform data
                           │
           ┌───────────────┼───────────────┐
           │                               │
   ┌───────▼────────┐             ┌────────▼───────┐
   │ backend-ai-api │             │backend-vitto-api│
   │    (3001)      │ ──────────► │    (3003)       │
   │  "The Brain"   │  decisions  │  "The Hands"    │
   │                │  & plans    │                  │
   │                │ ◄────────── │                  │
   │                │  outcomes   │                  │
   └────────────────┘  & learning └─────────────────┘

Key principle: The Brain produces decisions and plans. The Hands execute them and report outcomes. No circular dependency — information flows in one direction per concern.

Shared Infrastructure

Authentication

All three backends use AuthCoreModule from @libs-api/auth-core with the same JWT_SECRET. A JWT issued by backend-api is valid on ai-api and vitto-api. UnifiedAuthGuard runs globally on all backends.

MongoDB

All backends connect to the same MongoDB Atlas cluster. They use different logical databases. backend-ai-api has shared read access to gograb-api (backend-api's database) for user profile enrichment.

Environment Variables

In Railway (production), all backends share env vars via variable groups. In local development, the shared .env.local at monorepo root is read by all backends via NestJS ConfigModule.

Cross-Service Auth

Service-to-service calls use BACKEND_API_INTERNAL_TOKEN (same value as SYSTEM_TOKEN) in the Authorization: Bearer header. No separate service mesh or mTLS.

Extension & Frontend Routing

Hetzner Sandbox Orchestrator

The sandbox-orchestrator runs on Hetzner bare-metal servers (AX42-U, AX102-U). It is NOT a NestJS backend in our monorepo — it's a separate Express app deployed directly to the servers.

It manages:

• Firecracker microVMs (create, snapshot, exec, destroy)
• Git repositories (list, branches, commits, file tree, clone URLs)
• Host metrics (CPU, memory, disk, VM capacity)

Access pattern: backend-ai-api reaches it via SANDBOX_SERVER_URL + SANDBOX_API_KEY (native fetch()). After the consolidation, backend-vitto-api will reach it directly.

Port Reference

Rule: Never hardcode ports. Use yarn serve:* commands which read from .env.local. Never pass --port to backend serve commands (causes WebSocket 400 errors).