Architecture

How the Concierto platform fits together: Go backend, monorepo frontend, shared packages, and the daemon that runs agents.

Overview

Concierto is a Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Next.js    │────>│  Go Backend  │────>│   PostgreSQL     │
│   Frontend   │<────│  (Chi + WS)  │<────│   (pgvector)     │
└──────────────┘     └──────┬───────┘     └──────────────────┘
                            │
                     ┌──────┴───────┐
                     │ Agent Runtime│  (local daemon or hosted pool)
                     │ Claude/Codex/│
                     │ Cursor/…     │
                     └──────────────┘

The web interface is the front of house; the server only coordinates. Agents never run inside the server: they run on a runtime, either the local daemon on your machine or Concierto Cloud's managed worker pool. See How Concierto works for the product-level model.

Project structure

Directory	Purpose	Technology
`server/`	Go backend	Chi router, sqlc for DB, gorilla/websocket
`apps/web/`	Next.js frontend	App Router
`apps/desktop/`	Electron desktop app	electron-vite
`apps/docs/`	Documentation site	Fumadocs
`packages/core/`	Headless business logic	Zero react-dom, all-platform reuse
`packages/ui/`	Atomic UI components	Zero business logic, shadcn-based
`packages/views/`	Shared business pages	Zero `next/*`, zero react-router imports
`packages/tsconfig/`	Shared TypeScript config	—

Backend structure

Entry points (cmd/): server (HTTP API), concierto (CLI + daemon), migrate
Handlers (internal/handler/): one file per domain (issue, comment, agent, auth, daemon)
Real-time (internal/realtime/): a hub manages WebSocket clients; the server broadcasts events
Auth (internal/auth/ + internal/middleware/): JWT (HS256); middleware sets X-User-ID and X-User-Email
Task lifecycle (internal/service/task.go): enqueue → claim → start → complete/fail
Agent SDK (pkg/agent/): a unified Backend interface for executing prompts via the supported AI coding tools
Daemon (internal/daemon/): auto-detects CLIs, registers runtimes, polls for tasks
Database: PostgreSQL 17 with pgvector; sqlc generates code from SQL in pkg/db/queries/

Frontend architecture

Internal Packages pattern

All shared packages export raw .ts / .tsx files (no pre-compilation). The consuming app's bundler compiles them directly, which gives zero-config HMR and instant go-to-definition.

Package boundaries

packages/core/: zero react-dom, zero localStorage, zero UI libs. All Zustand stores live here.
packages/ui/: pure UI components, zero business logic, zero @nstack/core imports.
packages/views/: zero next/*, zero react-router-dom. Uses NavigationAdapter for routing.

State management

TanStack Query owns all server state (issues, users, workspaces, inbox).
Zustand owns all client state (UI selections, filters, drafts).
React Context is reserved for cross-cutting plumbing (WorkspaceIdProvider, NavigationProvider).

Data flow

Browser → ApiClient (core/api) → REST API (Chi handlers) → sqlc queries → PostgreSQL
Browser ← WSClient (core/api)  ← WebSocket ← Hub.Broadcast() ← Handlers / TaskService

Multi-tenancy

All queries filter by workspace_id. Membership checks gate access, and the X-Workspace-ID header routes requests to the correct workspace.