# Architecture Guide

This document explains what `codex-a2a` is responsible for, what remains inside Codex, and how requests move through the service.

## System Role

`codex-a2a` is an adapter layer between A2A clients and the Codex runtime.

It is responsible for:

- exposing A2A-facing HTTP+JSON and JSON-RPC endpoints
- normalizing stream, session, and interrupt contracts
- applying authentication, logging, and runtime-side guardrails

It is not responsible for:

- replacing Codex's own model/provider capability logic
- providing tenant isolation across multiple consumers by default
- hiding the fact that Codex may still need provider credentials at runtime

## Adapter Layers

```mermaid
flowchart LR
    Client["A2A Client / Hub / App"] --> Gateway["codex-a2a"]
    Gateway --> Contracts["A2A contracts\nstream/session/interrupt"]
    Gateway --> Ops["Auth / logging / deployment boundary"]
    Contracts --> Codex["Codex app-server / CLI runtime"]
    Ops --> Codex
    Codex --> Workspace["Shared workspace and provider credentials"]
```

This view emphasizes service responsibility boundaries rather than internal module structure. The root [README](../README.md) keeps the more implementation-oriented logical component view for first-time readers, while [maintainer-architecture.md](./maintainer-architecture.md) covers the internal module graph and request call chains for contributors.

## Request Flow

### Standard send/stream flow

1. Client calls the REST or JSON-RPC endpoint.
2. FastAPI validates transport shape and auth.
3. The adapter translates A2A message/task semantics into Codex runtime calls.
4. Codex runtime emits session events, stream chunks, and interrupt requests.
5. The service maps those into shared A2A-facing contracts before returning them to the client.

### Streaming flow

For streaming requests, the service does more than simple passthrough:

- classifies stream blocks into shared types such as `text`, `reasoning`, and `tool_call`
- preserves ordering and identity metadata
- emits interrupt lifecycle status updates
- publishes normalized usage data in final metadata when available

Detailed streaming contract: [Usage Guide](guide.md)

### Session flow

The service keeps a shared session continuation contract around `metadata.shared.session.id`, so clients can continue an existing Codex conversation without binding directly to provider-private request formats.

### Interrupt flow

When Codex asks for permission or answers, the service exposes:

- shared asked/resolved lifecycle metadata in stream status events
- callback methods through A2A JSON-RPC extensions
- lifecycle and type validation before forwarding callback replies

## Boundary Model

The service introduces a boundary, but not a full trust boundary.

### What the service boundary helps with

- stable client-facing contract shape
- auth enforcement on A2A entrypoints
- payload logging controls
- safer runtime defaults for secrets and health probing

### What still belongs to the Codex runtime boundary

- provider credential consumption
- workspace execution side effects
- model/provider-specific runtime behavior

That is why deployments should still be treated as trusted or controlled unless stronger isolation is added.

## Documentation Split

Use the docs by responsibility:

- [README](../README.md): project overview, quick-start path, and entry navigation
- [Usage Guide](guide.md): configuration, transport usage, and runtime examples
- [Maintainer Architecture Guide](maintainer-architecture.md): internal module boundaries, request call chains, and persistence touchpoints
- [Extension Specifications](extension-specifications.md): stable extension URI/spec index and public-vs-extended disclosure rules
- [Compatibility Guide](compatibility.md): current compatibility promises and stability expectations
- [Contributing Guide](../CONTRIBUTING.md): contributor workflow and validation
- [Security Policy](../SECURITY.md): threat model and disclosure guidance

Maintainers can regenerate optional upstream Codex reference snapshots with `scripts/sync_codex_docs.sh` when protocol comparison is needed.
