# stealthwhizz/pcp architecture

> Architecture diagram of the GitHub repository stealthwhizz/pcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stealthwhizz/pcp
- Repository: https://github.com/stealthwhizz/pcp

## Overview

#### Purpose and runtime
PCP is a self-hostable control plane for coding agents: durable task/memory management via MCP plus fleet monitoring via OpenTelemetry. The deployable application is one TypeScript Next.js App Router service rooted at `backend/`, importing browser UI from `frontend/`. Main web entry points include `backend/app/page.tsx`, `backend/app/dashboard/page.tsx`, and `backend/app/developer/page.tsx`.

#### HTTP/API boundary
Next route handlers expose the product API: browser authentication and dashboard reads, agent task/memory operations, MCP, and OTLP ingestion. Representative boundaries are `backend/app/api/auth/login/route.ts`, `backend/app/api/dashboard/route.ts`, and `backend/app/api/tasks/[taskId]/handoff/route.ts`. API handlers should remain thin wrappers around services and enforce organization-scoped access at this edge.

#### Identity and tenancy
Authentication uses locally managed credentials and signed cookie sessions; API/MCP/telemetry clients authenticate with bearer tokens tied to one organization. Core enforcement and persistence-facing account/token logic live in `backend/lib/auth.ts`, `backend/lib/session.ts`, and `backend/lib/services/tokens.ts`. The tenant boundary is `organizationId`, intended to scope every domain query and prevent cross-workspace data access.

#### Domain memory and task lifecycle
The core agent-memory model records tasks, checkpoints, handoffs, recovery state, memories, and explicit memory relationships. Task and memory APIs map to service-layer workflows in `backend/lib/services/tasks.ts`, `backend/lib/services/recovery.ts`, and `backend/lib/services/memory.ts`; routes include `backend/app/api/memory/relationships/route.ts` and `backend/app/api/tasks/[taskId]/checkpoints/route.ts`. This is the durable continuity path for agents across sessions.

#### MCP integration
MCP exposes the same task/memory capabilities to agents through hosted Streamable HTTP and local stdio. HTTP requests enter `backend/app/api/mcp/route.ts` and are handled through `backend/mcp/http.ts`; shared tool dispatch is in `backend/mcp/handlers.ts`. The local-server entry point, `backend/mcp/server.ts`, can bootstrap project-local `.pcp` guidance via `backend/mcp/bootstrap.ts`, while hosted clients operate solely through HTTPS and bearer tokens.

#### Telemetry and monitoring flow
OTLP logs, metrics, and traces arrive at dedicated endpoints, are normalized/redacted, then persisted as agent telemetry for dashboard aggregation. The pipeline is grounded in `backend/app/api/otel/v1/metrics/route.ts`, `backend/lib/otel/ingest.ts`, and `backend/lib/otel/normalize.ts`. Dashboard-facing portfolio, usage, and activity views are derived through `backend/lib/services/dashboard.ts` and `backend/lib/services/usage.ts`, rather than querying ingest payloads directly.

#### Persistence and deployment
Prisma defines the shared PostgreSQL graph and migration history in `backend/prisma/schema.prisma` and `backend/prisma/migrations/`. Database access is centralized in `backend/lib/db.ts`. Local development uses PostgreSQL via `backend/docker-compose.yml`; production targets Zerops using `backend/zerops.yml`, which builds Next.js, applies Prisma migrations, and runs the service with managed Postgres supplied through `DATABASE_URL`.

Main entry points: [`backend/lib/db.ts`](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/db.ts) (Database access), [`backend/lib/services/tasks.ts`](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/tasks.ts) (Task workflows), [`backend/mcp/handlers.ts`](https://github.com/stealthwhizz/pcp/blob/main/backend/mcp/handlers.ts) (MCP tool dispatch), [`backend/lib/services/memory.ts`](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/memory.ts) (Memory workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js control plane"]
  node_browser["Browser UI<br/>React UI"]
  node_pages["Web pages<br/>App Router pages<br/>[page.tsx]"]
  node_api["Product API<br/>Next route handlers<br/>[route.ts]"]
end

subgraph group_identity["Identity and tenancy"]
  node_auth_routes["Auth routes<br/>API route<br/>[route.ts]"]
  node_auth["Auth and sessions<br/>identity service<br/>[auth.ts]"]
  node_tokens["Organization tokens<br/>token service<br/>[tokens.ts]"]
end

subgraph group_domain["Agent continuity"]
  node_task_routes["Task and memory routes<br/>API routes<br/>[route.ts]"]
  node_tasks["Task workflows<br/>task service<br/>[tasks.ts]"]
  node_memory["Memory workflows<br/>memory service<br/>[memory.ts]"]
end

subgraph group_mcp["MCP interfaces"]
  node_mcp_http["Hosted MCP endpoint<br/>MCP API route<br/>[route.ts]"]
  node_mcp_handlers["MCP tool dispatch<br/>MCP handlers<br/>[handlers.ts]"]
  node_mcp_local["Local MCP server<br/>stdio server<br/>[server.ts]"]
end

subgraph group_telemetry["Telemetry and monitoring"]
  node_otlp["OTLP ingestion<br/>telemetry API route<br/>[route.ts]"]
  node_ingest["Telemetry pipeline<br/>ingest service<br/>[ingest.ts]"]
  node_dashboard["Dashboard aggregation<br/>dashboard service<br/>[dashboard.ts]"]
end

subgraph group_data["Persistence and deployment"]
  node_db[("Database access<br/>Prisma client<br/>[db.ts]")]
  node_schema[("PostgreSQL schema<br/>Prisma schema<br/>[schema.prisma]")]
  node_deployment{{"Production deployment<br/>Zerops service<br/>[zerops.yml]"}}
end

node_browser -->|"renders"| node_pages
node_browser -->|"calls"| node_api
node_pages -->|"reads"| node_dashboard
node_auth_routes -->|"authenticates"| node_auth
node_api -->|"enforces org access"| node_auth
node_auth -->|"validates bearer tokens"| node_tokens
node_task_routes -->|"delegates"| node_tasks
node_task_routes -->|"delegates"| node_memory
node_tasks -->|"records continuity"| node_memory
node_tasks -->|"persists"| node_db
node_memory -->|"persists"| node_db
node_mcp_http -->|"dispatches"| node_mcp_handlers
node_mcp_local -->|"shares dispatch"| node_mcp_handlers
node_mcp_handlers -->|"task tools"| node_tasks
node_mcp_handlers -->|"memory tools"| node_memory
node_otlp -->|"ingests"| node_ingest
node_ingest -->|"stores telemetry"| node_db
node_dashboard -->|"derives views"| node_db
node_api -->|"serves dashboard reads"| node_dashboard
node_db -.->|"implements"| node_schema
node_deployment -->|"runs"| node_pages
node_deployment -->|"uses managed Postgres"| node_db

click node_pages "https://github.com/stealthwhizz/pcp/blob/main/backend/app/page.tsx"
click node_api "https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/dashboard/route.ts"
click node_auth_routes "https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/auth/login/route.ts"
click node_auth "https://github.com/stealthwhizz/pcp/blob/main/backend/lib/auth.ts"
click node_tokens "https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/tokens.ts"
click node_task_routes "https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/tasks/%5BtaskId%5D/handoff/route.ts"
click node_tasks "https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/tasks.ts"
click node_memory "https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/memory.ts"
click node_mcp_http "https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/mcp/route.ts"
click node_mcp_handlers "https://github.com/stealthwhizz/pcp/blob/main/backend/mcp/handlers.ts"
click node_mcp_local "https://github.com/stealthwhizz/pcp/blob/main/backend/mcp/server.ts"
click node_otlp "https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/otel/v1/metrics/route.ts"
click node_ingest "https://github.com/stealthwhizz/pcp/blob/main/backend/lib/otel/ingest.ts"
click node_dashboard "https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/dashboard.ts"
click node_db "https://github.com/stealthwhizz/pcp/blob/main/backend/lib/db.ts"
click node_schema "https://github.com/stealthwhizz/pcp/blob/main/backend/prisma/schema.prisma"
click node_deployment "https://github.com/stealthwhizz/pcp/blob/main/backend/zerops.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_pages,node_api toneBlue
class node_auth_routes,node_auth,node_tokens toneAmber
class node_task_routes,node_tasks,node_memory toneMint
class node_mcp_http,node_mcp_handlers,node_mcp_local toneRose
class node_otlp,node_ingest,node_dashboard toneIndigo
class node_db,node_schema,node_deployment toneTeal
```

## Components

### Next.js control plane

Single deployable service rooted at backend/.

- **Browser UI**: React UI · Imported by the Next.js application.
- [Web pages](https://github.com/stealthwhizz/pcp/blob/main/backend/app/page.tsx): App Router pages · Authentication, dashboard, and developer entry points. · `backend/app/page.tsx`
- [Product API](https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/dashboard/route.ts): Next route handlers · Thin organization-scoped HTTP boundary. · `backend/app/api/dashboard/route.ts`

### Identity and tenancy

- [Auth routes](https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/auth/login/route.ts): API route · `backend/app/api/auth/login/route.ts`
- [Auth and sessions](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/auth.ts): identity service · Local credentials, signed cookies, and bearer authentication. · `backend/lib/auth.ts`
- [Organization tokens](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/tokens.ts): token service · Bearer tokens are tied to one organization. · `backend/lib/services/tokens.ts`

### Agent continuity

- [Task and memory routes](https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/tasks/%5BtaskId%5D/handoff/route.ts): API routes · `backend/app/api/tasks/[taskId]/handoff/route.ts`
- [Task workflows](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/tasks.ts): task service · Tasks, checkpoints, handoffs, and recovery state. · `backend/lib/services/tasks.ts`
- [Memory workflows](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/memory.ts): memory service · Durable memories and explicit relationships. · `backend/lib/services/memory.ts`

### MCP interfaces

- [Hosted MCP endpoint](https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/mcp/route.ts): MCP API route · Streamable HTTP for HTTPS clients. · `backend/app/api/mcp/route.ts`
- [MCP tool dispatch](https://github.com/stealthwhizz/pcp/blob/main/backend/mcp/handlers.ts): MCP handlers · Shared task and memory capability dispatch. · `backend/mcp/handlers.ts`
- [Local MCP server](https://github.com/stealthwhizz/pcp/blob/main/backend/mcp/server.ts): stdio server · Can bootstrap project-local .pcp guidance. · `backend/mcp/server.ts`

### Telemetry and monitoring

- [OTLP ingestion](https://github.com/stealthwhizz/pcp/blob/main/backend/app/api/otel/v1/metrics/route.ts): telemetry API route · Accepts logs, metrics, and traces. · `backend/app/api/otel/v1/metrics/route.ts`
- [Telemetry pipeline](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/otel/ingest.ts): ingest service · Normalizes, redacts, and persists agent telemetry. · `backend/lib/otel/ingest.ts`
- [Dashboard aggregation](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/services/dashboard.ts): dashboard service · Derives portfolio, usage, and activity views. · `backend/lib/services/dashboard.ts`

### Persistence and deployment

- [Database access](https://github.com/stealthwhizz/pcp/blob/main/backend/lib/db.ts): Prisma client · Centralized persistence access. · `backend/lib/db.ts`
- [PostgreSQL schema](https://github.com/stealthwhizz/pcp/blob/main/backend/prisma/schema.prisma): Prisma schema · Shared graph and migration history. · `backend/prisma/schema.prisma`
- [Production deployment](https://github.com/stealthwhizz/pcp/blob/main/backend/zerops.yml): Zerops service · Builds Next.js, migrates Prisma, and receives DATABASE_URL. · `backend/zerops.yml`

## Connections

- Browser UI → Web pages: renders
- Browser UI → Product API: calls
- Web pages → Dashboard aggregation: reads
- Auth routes → Auth and sessions: authenticates
- Product API → Auth and sessions: enforces org access
- Auth and sessions → Organization tokens: validates bearer tokens
- Task and memory routes → Task workflows: delegates
- Task and memory routes → Memory workflows: delegates
- Task workflows → Memory workflows: records continuity
- Task workflows → Database access: persists
- Memory workflows → Database access: persists
- Hosted MCP endpoint → MCP tool dispatch: dispatches
- Local MCP server → MCP tool dispatch: shares dispatch
- MCP tool dispatch → Task workflows: task tools
- MCP tool dispatch → Memory workflows: memory tools
- OTLP ingestion → Telemetry pipeline: ingests
- Telemetry pipeline → Database access: stores telemetry
- Dashboard aggregation → Database access: derives views
- Product API → Dashboard aggregation: serves dashboard reads
- Database access → PostgreSQL schema: implements
- Production deployment → Web pages: runs
- Production deployment → Database access: uses managed Postgres