Codex Lead Engineer
62 lines
2.6 KiB
Markdown
62 lines
2.6 KiB
Markdown
# 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.
|