# accordproject/apap architecture

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

- Interactive diagram: https://gitdiagram.com/accordproject/apap
- Repository: https://github.com/accordproject/apap

## Overview

APAP is an agreement server protocol and reference implementation, with a generated TypeScript client for agreement tools. The main REST workflow deploys or retrieves a template, creates and manages an agreement, then converts it to a requested format; capability discovery describes supported features. The server also exposes MCP, A2A, and Legal Context Protocol surfaces. Edges reflect README statements, excerpted wiring, or SOURCE INDEX references; unsampled route and subsystem internals are represented without speculative call chains.

Main entry points: [`server/index.ts`](https://github.com/accordproject/apap/blob/main/server/index.ts) (HTTP server), [`server/services/agreementService.ts`](https://github.com/accordproject/apap/blob/main/server/services/agreementService.ts) (Agreement service), [`server/services/templateService.ts`](https://github.com/accordproject/apap/blob/main/server/services/templateService.ts) (Template service), [`server/handlers/agreements.ts`](https://github.com/accordproject/apap/blob/main/server/handlers/agreements.ts) (Agreement REST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Protocol clients"]
  node_client_sdk["TypeScript SDK<br/>[apap.ts]"]
end

subgraph group_api["Server interfaces"]
  node_server["HTTP server<br/>[index.ts]"]
  node_templates_api["Template REST<br/>[templates.ts]"]
  node_agreements_api["Agreement REST<br/>[agreements.ts]"]
  node_capabilities["Capabilities<br/>[capabilities.ts]"]
  node_mcp["MCP interface<br/>[mcp.ts]"]
  node_a2a_api["A2A interface<br/>[a2a.ts]"]
  node_a2a_executor["A2A executor<br/>[executor.ts]"]
  node_lcp_api["LCP interface<br/>[lcp.ts]"]
  node_error_handler["Error mapping<br/>[errorHandler.ts]"]
end

subgraph group_domain["Agreement domain"]
  node_template_service["Template service<br/>[templateService.ts]"]
  node_agreement_service["Agreement service"]
  node_template_builder["Template processing<br/>[templatebuilder.ts]"]
  node_lcp_service["Legal context<br/>[lcpService.ts]"]
end

subgraph group_security["Identity and policy"]
  node_auth["Auth adapters<br/>[registry.ts]"]
  node_policy["Authorization policy<br/>[policy.ts]"]
end

subgraph group_data["Persistence and retrieval"]
  node_postgres[("PostgreSQL<br/>[schema.ts]")]
  node_template_retriever["Template retriever"]
  node_model_retriever["Model retriever"]
  node_allowlist["URL allowlist<br/>[allowlist.ts]"]
end

node_tool(("Agreement tool"))

node_tool -->|"uses"| node_client_sdk
node_client_sdk -->|"calls REST"| node_server
node_tool -->|"communicates REST"| node_server
node_server -->|"mounts"| node_templates_api
node_server -->|"mounts"| node_agreements_api
node_server -->|"mounts"| node_capabilities
node_server -->|"mounts"| node_mcp
node_server -->|"mounts"| node_lcp_api
node_server -->|"mounts"| node_a2a_api
node_server -->|"registers"| node_error_handler
node_templates_api -->|"delegates"| node_template_service
node_agreements_api -->|"delegates"| node_agreement_service
node_agreements_api -->|"uses"| node_template_builder
node_agreement_service -->|"builds template"| node_template_builder
node_agreement_service -->|"reads and writes"| node_postgres
node_template_service -->|"reads and writes"| node_postgres
node_template_service -->|"extracts archives"| node_template_builder
node_template_retriever -->|"checks URLs"| node_allowlist
node_model_retriever -->|"checks URLs"| node_allowlist
node_mcp -->|"invokes"| node_template_service
node_mcp -->|"invokes"| node_agreement_service
node_a2a_api -->|"dispatches"| node_a2a_executor
node_a2a_executor -->|"invokes"| node_template_service
node_a2a_executor -->|"invokes"| node_agreement_service
node_lcp_api -->|"delegates"| node_lcp_service
node_lcp_service -->|"converts agreement"| node_agreement_service
node_auth -.->|"supplies identity"| node_policy
node_template_service -->|"authorizes"| node_policy
node_agreement_service -->|"authorizes"| node_policy
node_error_handler -->|"maps DB conflicts"| node_postgres

click node_client_sdk "https://github.com/accordproject/apap/blob/main/client/typescript/apap.ts"
click node_server "https://github.com/accordproject/apap/blob/main/server/index.ts"
click node_templates_api "https://github.com/accordproject/apap/blob/main/server/handlers/templates.ts"
click node_agreements_api "https://github.com/accordproject/apap/blob/main/server/handlers/agreements.ts"
click node_capabilities "https://github.com/accordproject/apap/blob/main/server/handlers/capabilities.ts"
click node_mcp "https://github.com/accordproject/apap/blob/main/server/handlers/mcp.ts"
click node_a2a_api "https://github.com/accordproject/apap/blob/main/server/handlers/a2a.ts"
click node_a2a_executor "https://github.com/accordproject/apap/blob/main/server/a2a/executor.ts"
click node_lcp_api "https://github.com/accordproject/apap/blob/main/server/handlers/lcp.ts"
click node_template_service "https://github.com/accordproject/apap/blob/main/server/services/templateService.ts"
click node_agreement_service "https://github.com/accordproject/apap/blob/main/server/services/agreementService.ts"
click node_template_builder "https://github.com/accordproject/apap/blob/main/server/handlers/templatebuilder.ts"
click node_lcp_service "https://github.com/accordproject/apap/blob/main/server/services/lcpService.ts"
click node_auth "https://github.com/accordproject/apap/blob/main/server/auth/registry.ts"
click node_policy "https://github.com/accordproject/apap/blob/main/server/services/policy.ts"
click node_postgres "https://github.com/accordproject/apap/blob/main/server/db/schema.ts"
click node_template_retriever "https://github.com/accordproject/apap/blob/main/server/handlers/retrievers/HttpTemplateRetriever.ts"
click node_model_retriever "https://github.com/accordproject/apap/blob/main/server/handlers/retrievers/HttpModelRetriever.ts"
click node_allowlist "https://github.com/accordproject/apap/blob/main/server/handlers/retrievers/allowlist.ts"
click node_error_handler "https://github.com/accordproject/apap/blob/main/server/middleware/errorHandler.ts"

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_client_sdk toneBlue
class node_server,node_templates_api,node_agreements_api,node_capabilities,node_mcp,node_a2a_api,node_a2a_executor,node_lcp_api,node_error_handler toneAmber
class node_template_service,node_agreement_service,node_template_builder,node_lcp_service toneMint
class node_auth,node_policy toneRose
class node_postgres,node_template_retriever,node_model_retriever,node_allowlist,node_tool toneIndigo
```

## Components

### Protocol clients

- [TypeScript SDK](https://github.com/accordproject/apap/blob/main/client/typescript/apap.ts): `client/typescript/apap.ts`

### Server interfaces

- [HTTP server](https://github.com/accordproject/apap/blob/main/server/index.ts): `server/index.ts`
- [Template REST](https://github.com/accordproject/apap/blob/main/server/handlers/templates.ts): `server/handlers/templates.ts`
- [Agreement REST](https://github.com/accordproject/apap/blob/main/server/handlers/agreements.ts): `server/handlers/agreements.ts`
- [Capabilities](https://github.com/accordproject/apap/blob/main/server/handlers/capabilities.ts): `server/handlers/capabilities.ts`
- [MCP interface](https://github.com/accordproject/apap/blob/main/server/handlers/mcp.ts): `server/handlers/mcp.ts`
- [A2A interface](https://github.com/accordproject/apap/blob/main/server/handlers/a2a.ts): `server/handlers/a2a.ts`
- [A2A executor](https://github.com/accordproject/apap/blob/main/server/a2a/executor.ts): `server/a2a/executor.ts`
- [LCP interface](https://github.com/accordproject/apap/blob/main/server/handlers/lcp.ts): `server/handlers/lcp.ts`
- [Error mapping](https://github.com/accordproject/apap/blob/main/server/middleware/errorHandler.ts): `server/middleware/errorHandler.ts`

### Agreement domain

- [Template service](https://github.com/accordproject/apap/blob/main/server/services/templateService.ts): `server/services/templateService.ts`
- [Agreement service](https://github.com/accordproject/apap/blob/main/server/services/agreementService.ts): `server/services/agreementService.ts`
- [Template processing](https://github.com/accordproject/apap/blob/main/server/handlers/templatebuilder.ts): `server/handlers/templatebuilder.ts`
- [Legal context](https://github.com/accordproject/apap/blob/main/server/services/lcpService.ts): `server/services/lcpService.ts`

### Identity and policy

- [Auth adapters](https://github.com/accordproject/apap/blob/main/server/auth/registry.ts): `server/auth/registry.ts`
- [Authorization policy](https://github.com/accordproject/apap/blob/main/server/services/policy.ts): `server/services/policy.ts`

### Persistence and retrieval

- [PostgreSQL](https://github.com/accordproject/apap/blob/main/server/db/schema.ts): `server/db/schema.ts`
- [Template retriever](https://github.com/accordproject/apap/blob/main/server/handlers/retrievers/HttpTemplateRetriever.ts): `server/handlers/retrievers/HttpTemplateRetriever.ts`
- [Model retriever](https://github.com/accordproject/apap/blob/main/server/handlers/retrievers/HttpModelRetriever.ts): `server/handlers/retrievers/HttpModelRetriever.ts`
- [URL allowlist](https://github.com/accordproject/apap/blob/main/server/handlers/retrievers/allowlist.ts): `server/handlers/retrievers/allowlist.ts`

### Other components

- **Agreement tool**

## Connections

- Agreement tool → TypeScript SDK: uses (evidence: `README.md`)
- TypeScript SDK → HTTP server: calls REST (evidence: `README.md`)
- Agreement tool → HTTP server: communicates REST (evidence: `README.md`)
- HTTP server → Template REST: mounts (evidence: `server/index.ts`)
- HTTP server → Agreement REST: mounts (evidence: `server/index.ts`)
- HTTP server → Capabilities: mounts (evidence: `server/index.ts`)
- HTTP server → MCP interface: mounts (evidence: `server/index.ts`)
- HTTP server → LCP interface: mounts (evidence: `server/index.ts`)
- HTTP server → A2A interface: mounts (evidence: `server/index.ts`)
- HTTP server → Error mapping: registers (evidence: `server/index.ts`)
- Template REST → Template service: delegates
- Agreement REST → Agreement service: delegates (evidence: `server/handlers/agreements.ts`)
- Agreement REST → Template processing: uses (evidence: `server/handlers/agreements.ts`)
- Agreement service → Template processing: builds template (evidence: `server/services/agreementService.ts`)
- Agreement service → PostgreSQL: reads and writes (evidence: `server/services/agreementService.ts`)
- Template service → PostgreSQL: reads and writes (evidence: `server/services/templateService.ts`)
- Template service → Template processing: extracts archives (evidence: `server/services/templateService.ts`)
- Template retriever → URL allowlist: checks URLs (evidence: `server/handlers/retrievers/HttpTemplateRetriever.ts`)
- Model retriever → URL allowlist: checks URLs (evidence: `server/handlers/retrievers/HttpModelRetriever.ts`)
- MCP interface → Template service: invokes (evidence: `server/handlers/mcp.ts`)
- MCP interface → Agreement service: invokes (evidence: `server/handlers/mcp.ts`)
- A2A interface → A2A executor: dispatches (evidence: `server/handlers/a2a.ts`)
- A2A executor → Template service: invokes (evidence: `server/a2a/executor.ts`)
- A2A executor → Agreement service: invokes (evidence: `server/a2a/executor.ts`)
- LCP interface → Legal context: delegates (evidence: `server/handlers/lcp.ts`)
- Legal context → Agreement service: converts agreement (evidence: `server/services/lcpService.ts`)
- Auth adapters → Authorization policy: supplies identity
- Template service → Authorization policy: authorizes (evidence: `server/services/templateService.ts`)
- Agreement service → Authorization policy: authorizes (evidence: `server/services/agreementService.ts`)
- Error mapping → PostgreSQL: maps DB conflicts (evidence: `server/middleware/errorHandler.ts`)
