MCP-Project-bus/docs/ARCHITECTURE.md

Architecture

Boundary

The Project Bus coordinates formal project events. It does not execute source code, clone repositories, inspect artifacts, send chat messages, implement a project methodology, or decide what a project should build. Those activities remain with authenticated actors and external systems.

Components

1. ProjectBusRequestHandler implements a small stateless MCP Streamable HTTP transport over JSON-RPC 2.0.
2. AuthProvider turns transport credentials into an immutable principal.
3. MCPApplication publishes tools and maps calls to domain operations.
4. ProjectBusService enforces role, lifecycle, independence, idempotency, and gate invariants.
5. Database owns migration and transaction boundaries.
6. SQLite relational projections support current-state queries; event_log is the immutable ordered synchronization source.

Write path

A mutating call is authenticated before tool dispatch. The service opens BEGIN IMMEDIATE, resolves the principal to an active project membership, checks the idempotency tuple (project, actor, key), validates current state, updates the relevant projection, appends exactly one event, stores the canonical response, and commits.

The event and projection update therefore succeed or fail together. Idempotency replays return the original response without adding an event.

Event ordering and cursors

SQLite allocates a monotonic integer cursor for each event. sync_since filters by project, returns ascending cursors, and returns the last delivered cursor. Consumers persist that value only after processing the response. The cursor is global to the database, so gaps within a project's stream are normal. Consumers must not infer missing project events from gaps.

This is pull synchronization. The MCP server does not wake a ChatGPT thread or push into a dormant CLI session.

State model

Work packages move through:

OPEN → CLAIMED → RESULT_SUBMITTED → IN_REVIEW → REVIEWED → ACCEPTED|REJECTED

HOLD leaves a reviewed package in REVIEWED. A new review can be requested after a completed review. This MVP treats corrections after CHANGES_REQUESTED as a new work package. It does not support replacing the result on the reviewed work package and never silently overwrites submitted result evidence.

Trust boundaries

• Authentication proves an external subject; project membership grants a role.
• The database is trusted to enforce integrity and append-only triggers.
• Artifact URIs and commit hashes are references, not trusted content.
• Reverse proxy identity headers are not consumed by the built-in adapter.