Architecture: Content Intelligence Server

The Content Intelligence (CI) server architecture is designed to provide high-performance project insights while maintaining strict organizational data isolation. By leveraging a modular architecture built on Hono and TypeScript, the server separates its public-facing communication surfaces from its core domain logic.

Composition Root (src/app.ts)

src/app.ts serves as the composition root for the entire service. It is responsible for orchestrating the server's lifecycle and dependency injection. By centralizing the creation of the Hono application, it ensures that all endpoints—whether intended for LLM agents or standard web clients—are consistently configured with:

• Middleware Infrastructure: Global enforcement of security policies, including bearer token authentication for the MCP boundary and origin restriction (CORS) for web surfaces.
• Routing Composition: Logical separation of API routes (/api/v1/ci/*), health checks (/health/*), and the Streamable HTTP MCP endpoint (/mcp).
• Stateless Execution: The application remains stateless, relying on the underlying gateway implementations to retrieve project state dynamically. This allows the server to scale horizontally across multiple instances or environments.

The Dual-Surface Contract

The server maintains a clear separation of concerns between its two public interfaces, allowing it to satisfy both agentic and programmatic use cases:

• MCP Surface (/mcp): This layer acts as a protocol-compliant tool provider. It translates human-friendly prompts and resource requests into structured tool calls. This allows large language models and autonomous agents to "triage" project loops, list findings, and pull health confidence signals using the official MCP standard.
• HTTP API Surface (/api/v1/ci/*): This is the authoritative interface for programmatic access. It follows a RESTful pattern, providing granular data access—such as GET /overview or POST /quality/:itemId—without the overhead of the MCP protocol. This API is used by dashboards, CI pipelines, and reporting tools to consume the server's processed intelligence.

Nexus Gateway and Data Bridging

At the core of the system lies the Nexus Gateway (src/nexus/nexus-gateway.ts). This component bridges the gap between raw, structured data in the Nexus Postgres item-store and the semantic, agentic intelligence layer.

• Projection Logic: The gateway transforms raw database records (e.g., ticket state, timestamps, effort seconds) into a high-level TicketInput or WorkUnit domain object that is easily consumable by LLMs.
• Assessment Routing: The gateway acts as a facade, directing complex analytical requests to configured LLM Assessors. These assessors utilize specific prompt templates—ranging from effort prediction to mismatch detection—to augment database data with model-driven narrative and risk analysis.
• Organization Scoping: To ensure multi-tenancy security, every gateway interaction passes through an OrganizationScopeEnforcer. This middleware dynamically validates database queries, ensuring that every SQL operation is scoped to the requesting organization and preventing cross-tenant data leakage.

Component Relationships

The architecture follows a strict downward dependency flow:

1. Transport Layer (src/app.ts): Handles HTTP and MCP request/response cycles.
2. Tool/Presenter Layer (src/mcp/, src/router/): Translates transport-specific inputs into requests for the Gateway.
3. Domain Gateway (src/nexus/, src/content-intelligence/): Executes logic to retrieve data from Nexus or the intelligent LLM backend.
4. Intelligence Engine (src/llm/, src/findings/): The "brain" of the server, where LLMs generate assessments and the findings engine monitors thresholds for alerts.
5. Bootstrap Layer (src/bootstrap/): Manages the instantiation of the database client and LLM adapter, ensuring the server can switch between "Embedded" (local Postgres) and "Remote" (API-gateway) modes seamlessly based on environment configuration.

This design enables developers to swap the underlying persistence or inference backends with minimal impact to the public API surface, ensuring that the system can evolve alongside the team's data maturity.

Overview