Architecture#

Co-Vibe has one shared server.

That server owns:

web UI
API routes
MCP tools
database access
auth checks

Developers and agents do not write directly to the database.

Runtime Shape#

diagram

Developer browser
  -> Co-Vibe UI
  -> server API
  -> PostgreSQL locally, in rehearsal, and on Cloud SQL in production

Local coding agent
  -> Co-Vibe MCP endpoint
  -> server validation
  -> PostgreSQL locally, in rehearsal, and on Cloud SQL in production

First Deployment#

For dogfood, one machine runs the server.

Other developers connect to that machine over the local network or a hosted preview URL.

The server prints:

UI URL
MCP URL
auth mode
WorkOS callback mismatch warning when local ports differ

/api/health is the deployment health endpoint for browser and agent readiness checks.

It checks required schema tables and columns so stale PostgreSQL schemas fail loudly before users connect agents.

npm run doctor checks the local Node version, install policy, schema/tool health, and warns when the shared server is not reachable. npm run setup runs the PostgreSQL initializer and then the same doctor checks so a fresh clone has a single setup command before npm run dev.

For hosted rehearsals, Co-Vibe ships as a standalone Next.js container. The container runs node server.js from .next/standalone, stores uploads on /app/data, connects to PostgreSQL, and final customer handoff is verified after deploy with npm run readiness:handoff. The co-vibe.dev GCP production path must use Cloud Run plus Cloud SQL for PostgreSQL before customer traffic. See docs/engineering/hosting.md and docs/engineering/gcp-production.md.

Boundaries#

UI reads current state and timelines from server APIs.

MCP tools write structured events through server logic.

Metrics are derived from tasks, workstreams, sessions, usage events, warnings, and completion timestamps.

Dashboard metrics include totals plus per-developer usage and active work grouped by project.

The console is intentionally limited to six pages with dedicated URLs: /workstreams, /performance, /coordination, /analytics, /activity, and /settings. Coordination has two routed tabs: the coordination monitor at /coordination and the local git graph at /coordination/graph. Developer profiles are Performance drilldowns at /performance/developers/<handle>. Separate overview, metrics, team-now, insights, warning, and setup pages are not product surfaces; their data belongs inside one of those six pages. Outside the console, the root / is the public marketing page for signed-out visitors (/landing redirects to it), /docs renders this repo's markdown documentation (grouped sidebar + per-page table of contents, read from docs/ at request time), /setup/authorize is the device-flow approval page for covibe-local setup, and /share/<token> serves frozen public share-link snapshots without auth.

Performance metrics are derived from tasks, sessions, usage events, managed agent profiles, and agent_spans. The view is organized into Overview, Developers, Agents & cost, and Diagnostics sections so team health and individual developer performance are visible first, while deeper agent, spend, trace, alert, and benchmark diagnostics stay available without making the default page a long duplicated report. It includes per-developer rollups, current-vs-previous trend comparisons, per-developer activity grids, manager-ready weekly operating pulse and team scorecards, manager performance briefs with wins, risks, and lead actions, live agent monitoring for active/stale sessions, error pressure, spend, and manager actions, manager drilldowns by developer, status, and query across tasks, sessions, agents, and spans, alert triage for failing agents, idle sessions, stale sessions, and spend spikes, collaboration health scorecards from blockers, decisions, and overlap warnings, developer comparison matrix, developer operating-target attainment, developer and managed-agent leaderboards, managed-agent registry health with owner, utilization, reliability, and cost-per-session guidance, agent insight reports with working/hindering/quick-win recommendations, developer review cards, AI spend allocation by developer and model, selectable developer profiles, per-developer task ledgers, deterministic action reports and insights, session score/duration/tool rows, task owner/status/cost rows, recent trace-span drilldowns, agent rows, model spend, and a selectable team activity grid with daily event, completion, span, token, cost, and active-developer rollups. Usage counters include model, provider, token counts, cost, latency, and status without capturing raw prompts or model responses.

Workstreams reads planned tasks and planned workstreams from structured storage so future work is visible before an agent starts editing.

The Workstreams page also plans work: "Plan task" and "Plan workstream" forms POST to cookie-authenticated /api/tasks and /api/workstreams routes that run the same server-side planning core as the MCP plan operations (developer-scoped, overlap-checked, no MCP tokens). Escalated overlap candidates are shown in the console and require an explicit confirm before the planned item is created.

Settings owns Agent Setup, MCP token inventory, local companion commands, tenant/account administration, a read-only Connected repos list (each developer machine's registered repos with synced/pending/excluded state, reported by companion heartbeats — repo basenames only, never absolute paths), and a tenant-admin-only Danger zone. Coordination reads blocker, decision, code-claim, and peer-message work events so leads and agents can scan current risks without opening a summary.

The machine companion keeps itself current through the same heartbeat. A build-time manifest (public/downloads/co-vibe.json, written next to the served tarball so its version and sha256 can never disagree with the bytes) gives the server a single source of truth for the hosted companion. Each watch tick the companion reports its installed version on the session-less heartbeat; the server answers with that manifest's version and hash plus an update_available convergence flag. A --service run on an npm-managed install then downloads the tarball, verifies its sha256, npm installs it without touching the host project's package.json or lockfile, boot-checks the new install (auto-reverting on failure), and exits 0 so launchd/systemd respawn the new code — see docs/engineering/device-setup.md.

The Local graph tab renders per-repo git trees assembled on the server from snapshot-fed repo_commits and local_worktrees rows: one independent tree per repository (localGraphs in /api/state), with uncommitted local head nodes above committed history, label rows separating the two groups, short shas on committed rows, and private teammates redacted in place as @private.

Workstream dashboard rows include linked task counts and recent linked task titles derived from tasks.workstream_id.

Activity reads completed tasks and workstreams plus their completion event summaries from structured records.

Dashboard state and weekly summary payloads use bounded history reads so long dogfood runs do not create unbounded API responses.

Overlap checks happen on the server.

Parallel work audits reuse server overlap scoring to compare work that is already active or recently completed.

The dashboard audit route uses the same server audit module as MCP and does not mint MCP tokens.

Audit conflict details are stored in work_events.payload_json, which lets dashboard state restore the latest audit and weekly summaries report audit conflicts.

Auth maps a human to a developer inside a tenant and selected workspace. In WorkOS mode, AuthKit organizationId maps to a Co-Vibe tenant/company. Co-Vibe workspaces are team/project spaces below that tenant, not WorkOS Organizations. Tenant membership stores account-level admin or member; workspace membership scopes product reads and writes. Settings lets tenant admins rename the tenant, create workspaces inside the current tenant, and create admin/member users in the WorkOS organization through invitation email or an admin-set initial password. Initial passwords are passed to WorkOS only and are not stored in Co-Vibe. Settings also updates profile name/handle and requests WorkOS password resets while keeping email immutable. The Settings Danger zone lets a tenant admin reset the tenant's work data after typing the tenant name to confirm (POST /api/workspace/reset, admin-only): every workspace's tasks, workstreams, sessions, events, usage telemetry, snapshots, and embeddings are deleted inside per-workspace scoped transactions, while tenants, workspaces, developers, memberships, MCP tokens, and device grants are kept so agents stay connected; one workspace.data_reset provenance event records the per-table counts, and the route is idempotent on partial failure. Hosted PostgreSQL starts without a fake tenant/workspace; the post-auth /onboarding page creates the first tenant and workspace, and ordinary sign-in requires an existing membership. Local-dev uses the same /onboarding page backed by PostgreSQL instead of auto-selecting a default developer. Local-dev may store a covibe_tenant selector cookie so tenant onboarding can be tested without WorkOS; WorkOS mode ignores that cookie and trusts AuthKit organizationId.

MCP tokens map to the developer and workspace that created them. Agent work is logged on behalf of that token owner, not on behalf of a free-form agent claim. Tokens may carry a typed agent_type (claude-code, codex, cursor); a typed token's session attribution overrides the agent's self-reported type. The device-flow setup (/api/setup/device*, approved at /setup/authorize) mints one typed token per requested agent — see docs/engineering/device-setup.md.

In WorkOS mode, src/proxy.ts installs AuthKit proxy headers for the dashboard and protected UI APIs.

The dashboard auth gate sends unauthenticated users to /auth/sign-in (which redirects to hosted AuthKit in WorkOS mode) and authenticated-but-tenantless users to /onboarding; protected UI APIs return 401 when no WorkOS session is present.

Local-only route handlers also check auth status directly and return blocked auth responses when production WorkOS config is incomplete.

The JSON MCP route is not cookie-protected because it authenticates with developer MCP tokens.

The health route is public but only returns aggregate readiness signals: database, schema, MCP tool count, auth mode, missing table names, and missing column names.

Modules#

Current folders:

src/app/ for Next.js routes and pages
src/server/ for server actions, APIs, auth, and database access
src/server/db/ for schema and migrations
src/server/mcp/ for MCP tool dispatch, task tools, workstream tools, sessions, and summaries
src/server/overlap/ for duplicate-work checks (see overlap-precision.md for the escalation signals)
src/server/repositories/ for table reads and writes
src/features/console/ for the dashboard UI and its panels
src/features/landing/ for the public marketing page sections
scripts/ for one-off or operational scripts
scripts/python/ for Python support scripts, if needed
tests/ for cross-feature and browser tests

Keep every file under 300 lines.

Python Boundary#

Python may be used for support jobs, not hidden app behavior.

Good Python uses:

scoring overlap candidates
generating weekly summary drafts
analyzing usage/session metrics
running security or repo-health checks
importing or exporting structured data

Bad Python uses:

duplicating server business logic
bypassing the database layer
writing core state outside the server
adding untested scripts nobody knows how to run

If a Python script changes product behavior, it needs tests and docs.

No Deferred Code#

Do not add routes or components for future features unless they are wired and tested.

Future ideas belong in docs, not unused code.