Architecture Overview

System diagram, five binaries, project layout, and request lifecycle.

System Architecture

Moca runs as a cluster of five stateless processes behind a reverse proxy (Caddy/NGINX):

                    ┌─────────────────┐
                    │  Reverse Proxy  │
                    │  (Caddy/NGINX)  │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
       ┌──────┴──────┐ ┌────┴────┐  ┌──────┴──────┐
       │ moca-server  │ │ moca-   │  │ moca-server │
       │  (HTTP/WS)   │ │ server  │  │  (HTTP/WS)  │
       └──────┬───────┘ └────┬────┘  └──────┬──────┘
              │              │              │
    ┌─────────┴──────────────┴──────────────┴─────────┐
    │                   PostgreSQL 16+                 │
    │            (schema-per-tenant isolation)         │
    ├──────────────────────────────────────────────────┤
    │                     Redis 7+                     │
    │     (DB 0: cache, DB 1: queue, DB 2: sessions,  │
    │                  DB 3: pub/sub)                  │
    ├──────────────────────────────────────────────────┤
    │              Meilisearch v1.12                   │
    │         (tenant-prefixed indexes)                │
    └──────────────────────────────────────────────────┘
              │              │              │
       ┌──────┴──────┐ ┌────┴─────┐ ┌─────┴───────┐
       │ moca-worker  │ │ moca-    │ │ moca-outbox │
       │ (job consumer)│ │scheduler │ │ (DB→Kafka)  │
       └──────────────┘ └──────────┘ └─────────────┘

Five Binaries

Binary	Scaling	Purpose
moca-server	Horizontal	HTTP + WebSocket API, serves Desk static assets
moca-worker	Horizontal	Redis Streams job consumer with DLQ
moca-scheduler	Single leader	Cron job trigger (Redis distributed lock)
moca-outbox	Single leader	Transactional outbox poller (DB events to Kafka/Redis)
moca	CLI	Project init, site management, development, operations

In development mode, moca serve runs server + worker + scheduler in-process.

Project Layout

cmd/                    # Binary entry points
  moca/                 # CLI (152+ commands via Cobra)
  moca-server/          # HTTP + WebSocket server
  moca-worker/          # Background job consumer
  moca-scheduler/       # Cron scheduler
  moca-outbox/          # Transactional outbox poller
pkg/                    # Public framework packages
  meta/                 # MetaType registry, schema compiler
  document/             # Document runtime, lifecycle engine
  orm/                  # PostgreSQL adapter, query builder
  api/                  # REST API gateway, middleware
  auth/                 # Authentication, permissions
  hooks/                # Hook registry, event dispatcher
  apps/                 # App manifest, loader, installer
  tenancy/              # Multitenancy, site manager
  queue/                # Redis Streams jobs
  events/               # Event emitter, outbox
  search/               # Meilisearch indexer
  observe/              # Logging, health checks, metrics
  backup/               # Backup utilities
  cli/                  # CLI command registry
internal/               # Private implementation
  config/               # YAML config parser
  drivers/              # Redis client factory
  context/              # CLI context resolver
  output/               # CLI output formatters
  process/              # Goroutine supervisor
  serve/                # HTTP server composition
  scaffold/             # Project scaffolding templates
pkg/builtin/core/       # Builtin framework core doctypes (User, Role, DocType, etc.)
desk/                   # React 19 frontend (TypeScript, Vite, TailwindCSS)

Request Lifecycle

1. Request arrives at reverse proxy
2. Routed to moca-server instance
3. Middleware chain: Request ID -> CORS -> Rate Limit -> Auth -> Site Resolution
4. Site resolver determines tenant from subdomain/header/path
5. Per-tenant connection pool sets PostgreSQL search_path
6. API handler executes document CRUD via Document Runtime
7. Document lifecycle hooks fire (BeforeInsert, Validate, AfterSave, etc.)
8. Events published via transactional outbox (same DB transaction)
9. Response returned to client

Related

• MetaType System
• Document Runtime
• Query Engine
• Data & Infrastructure