# redjijb/sodboys-fieldops architecture

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

- Interactive diagram: https://gitdiagram.com/redjijb/sodboys-fieldops
- Repository: https://github.com/redjijb/sodboys-fieldops
- Video tour (about a minute): https://gitdiagram.com/redjijb/sodboys-fieldops/video

## Overview

D-Central FieldOps is a clean-slate, D-Central-native field-operations backend intended to replace fieldops-system. Its current documented status is Phase 1: foundational identity, capability authorization, and MCP skeleton, with no domain logic. The repository also contains a REST façade and a broad set of operational domain modules, but the README cautions that implementation and verification status vary. The graph shows the evidenced runtime entry points and identity/storage relationships; several domain branches are grouped because their route and tool internals were not sampled.

Main entry points: [`src/facade/routes`](https://github.com/redjijb/sodboys-fieldops/tree/main/src/facade/routes) (REST route handlers), [`src/mcp/tools`](https://github.com/redjijb/sodboys-fieldops/tree/main/src/mcp/tools) (MCP tools), [`src/identity/capabilities.ts`](https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/capabilities.ts) (Capability grants), [`src/facade/server.ts`](https://github.com/redjijb/sodboys-fieldops/blob/main/src/facade/server.ts) (REST façade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Runtime interfaces"]
  node_rest["REST façade<br/>[server.ts]"]
  node_router["Route dispatch<br/>[router.ts]"]
  node_rest_routes["REST route handlers"]
  node_mcp_server["MCP tool server<br/>[server.ts]"]
  node_mcp_http["MCP HTTP transport<br/>[http.ts]"]
  node_mcp_stdio["MCP stdio transport<br/>[stdio.ts]"]
end

subgraph group_operations["Field operations"]
  node_mcp_tools["MCP tools"]
  node_domain_core["People and time"]
  node_domain_resources["Sites and resources"]
  node_domain_work["Work and reporting"]
  node_domain_commerce["Procurement and spend"]
  node_domain_comms["Notifications and chat"]
  node_domain_admin["Admin and integrations"]
end

subgraph group_identity["Identity and authorization"]
  node_facade_auth["REST authorization<br/>[auth.ts]"]
  node_capabilities["Capability grants<br/>[capabilities.ts]"]
  node_access_tokens["Access tokens<br/>[accessToken.ts]"]
  node_did["DID resolution<br/>[did.ts]"]
  node_keys["Identity keys<br/>[keys.ts]"]
end

subgraph group_persistence["Persistence"]
  node_db_pool[("Postgres pool<br/>[pool.ts]")]
  node_db_migrate["Database migration<br/>[migrate.ts]"]
end

node_caller(("API or agent client"))

node_rest -->|"dispatches"| node_router
node_rest -->|"registers"| node_rest_routes
node_rest -.->|"serves requests"| node_caller
node_router -.->|"invokes handlers"| node_rest_routes
node_rest_routes -->|"authorizes"| node_facade_auth
node_rest_routes -->|"calls"| node_domain_admin
node_rest_routes -->|"calls"| node_domain_core
node_rest_routes -->|"calls"| node_domain_commerce
node_rest_routes -->|"calls"| node_domain_work
node_mcp_http -->|"serves"| node_mcp_server
node_mcp_stdio -.->|"serves"| node_mcp_server
node_mcp_server -->|"registers"| node_mcp_tools
node_mcp_tools -->|"calls"| node_domain_resources
node_mcp_tools -->|"calls"| node_domain_comms
node_mcp_tools -->|"calls"| node_domain_commerce
node_mcp_tools -->|"calls"| node_domain_work
node_mcp_tools -->|"checks access"| node_capabilities
node_facade_auth -->|"verifies"| node_access_tokens
node_facade_auth -->|"checks standing grant"| node_capabilities
node_capabilities -->|"queries grants"| node_db_pool
node_capabilities -->|"verifies credential"| node_did
node_did -->|"loads local key"| node_keys
node_keys -->|"stores keys"| node_db_pool
node_access_tokens -->|"resolves identity"| node_did
node_db_migrate -->|"uses pool"| node_db_pool
node_rest_routes -.->|"returns responses"| node_caller

click node_rest "https://github.com/redjijb/sodboys-fieldops/blob/main/src/facade/server.ts"
click node_router "https://github.com/redjijb/sodboys-fieldops/blob/main/src/facade/router.ts"
click node_rest_routes "https://github.com/redjijb/sodboys-fieldops/tree/main/src/facade/routes"
click node_mcp_server "https://github.com/redjijb/sodboys-fieldops/blob/main/src/mcp/server.ts"
click node_mcp_http "https://github.com/redjijb/sodboys-fieldops/blob/main/src/mcp/transports/http.ts"
click node_mcp_stdio "https://github.com/redjijb/sodboys-fieldops/blob/main/src/mcp/transports/stdio.ts"
click node_mcp_tools "https://github.com/redjijb/sodboys-fieldops/tree/main/src/mcp/tools"
click node_domain_core "https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain"
click node_domain_resources "https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain"
click node_domain_work "https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain"
click node_domain_commerce "https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain"
click node_domain_comms "https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain"
click node_domain_admin "https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain"
click node_facade_auth "https://github.com/redjijb/sodboys-fieldops/blob/main/src/facade/auth.ts"
click node_capabilities "https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/capabilities.ts"
click node_access_tokens "https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/accessToken.ts"
click node_did "https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/did.ts"
click node_keys "https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/keys.ts"
click node_db_pool "https://github.com/redjijb/sodboys-fieldops/blob/main/src/db/pool.ts"
click node_db_migrate "https://github.com/redjijb/sodboys-fieldops/blob/main/src/db/migrate.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_rest,node_router,node_rest_routes,node_mcp_server,node_mcp_http,node_mcp_stdio,node_caller toneBlue
class node_mcp_tools,node_domain_core,node_domain_resources,node_domain_work,node_domain_commerce,node_domain_comms,node_domain_admin toneAmber
class node_facade_auth,node_capabilities,node_access_tokens,node_did,node_keys toneMint
class node_db_pool,node_db_migrate toneRose
```

## Components

### Runtime interfaces

- [REST façade](https://github.com/redjijb/sodboys-fieldops/blob/main/src/facade/server.ts): `src/facade/server.ts`
- [Route dispatch](https://github.com/redjijb/sodboys-fieldops/blob/main/src/facade/router.ts): `src/facade/router.ts`
- [REST route handlers](https://github.com/redjijb/sodboys-fieldops/tree/main/src/facade/routes): `src/facade/routes`
- [MCP tool server](https://github.com/redjijb/sodboys-fieldops/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [MCP HTTP transport](https://github.com/redjijb/sodboys-fieldops/blob/main/src/mcp/transports/http.ts): `src/mcp/transports/http.ts`
- [MCP stdio transport](https://github.com/redjijb/sodboys-fieldops/blob/main/src/mcp/transports/stdio.ts): `src/mcp/transports/stdio.ts`

### Field operations

- [MCP tools](https://github.com/redjijb/sodboys-fieldops/tree/main/src/mcp/tools): `src/mcp/tools`
- [People and time](https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain): `src/domain`
- [Sites and resources](https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain): `src/domain`
- [Work and reporting](https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain): `src/domain`
- [Procurement and spend](https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain): `src/domain`
- [Notifications and chat](https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain): `src/domain`
- [Admin and integrations](https://github.com/redjijb/sodboys-fieldops/tree/main/src/domain): `src/domain`

### Identity and authorization

- [REST authorization](https://github.com/redjijb/sodboys-fieldops/blob/main/src/facade/auth.ts): `src/facade/auth.ts`
- [Capability grants](https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/capabilities.ts): `src/identity/capabilities.ts`
- [Access tokens](https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/accessToken.ts): `src/identity/accessToken.ts`
- [DID resolution](https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/did.ts): `src/identity/did.ts`
- [Identity keys](https://github.com/redjijb/sodboys-fieldops/blob/main/src/identity/keys.ts): `src/identity/keys.ts`

### Persistence

- [Postgres pool](https://github.com/redjijb/sodboys-fieldops/blob/main/src/db/pool.ts): `src/db/pool.ts`
- [Database migration](https://github.com/redjijb/sodboys-fieldops/blob/main/src/db/migrate.ts): `src/db/migrate.ts`

### Other components

- **API or agent client**

## Connections

- REST façade → Route dispatch: dispatches (evidence: `src/facade/server.ts`)
- REST façade → REST route handlers: registers (evidence: `src/facade/server.ts`)
- REST façade → API or agent client: serves requests
- Route dispatch → REST route handlers: invokes handlers (evidence: `src/facade/routes/webhookTargets.ts`)
- REST route handlers → REST authorization: authorizes (evidence: `src/facade/routes/webhookTargets.ts`)
- REST route handlers → Admin and integrations: calls (evidence: `src/facade/routes/webhookTargets.ts`)
- REST route handlers → People and time: calls (evidence: `src/facade/routes/fieldTime.ts`)
- REST route handlers → Procurement and spend: calls (evidence: `src/facade/routes/procurement.ts`)
- REST route handlers → Work and reporting: calls (evidence: `src/facade/routes/payroll.ts`)
- MCP HTTP transport → MCP tool server: serves (evidence: `src/mcp/transports/http.ts`)
- MCP stdio transport → MCP tool server: serves
- MCP tool server → MCP tools: registers (evidence: `src/mcp/server.ts`)
- MCP tools → Sites and resources: calls (evidence: `src/mcp/tools/assets.ts`)
- MCP tools → Notifications and chat: calls (evidence: `src/mcp/tools/notifications.ts`)
- MCP tools → Procurement and spend: calls (evidence: `src/mcp/tools/orders.ts`)
- MCP tools → Work and reporting: calls (evidence: `src/mcp/tools/spending.ts`)
- MCP tools → Capability grants: checks access
- REST authorization → Access tokens: verifies (evidence: `src/facade/auth.ts`)
- REST authorization → Capability grants: checks standing grant (evidence: `src/facade/auth.ts`)
- Capability grants → Postgres pool: queries grants (evidence: `src/identity/capabilities.ts`)
- Capability grants → DID resolution: verifies credential (evidence: `src/identity/capabilities.ts`)
- DID resolution → Identity keys: loads local key (evidence: `src/identity/did.ts`)
- Identity keys → Postgres pool: stores keys (evidence: `src/identity/keys.ts`)
- Access tokens → DID resolution: resolves identity (evidence: `src/identity/accessToken.ts`)
- Database migration → Postgres pool: uses pool (evidence: `src/db/migrate.ts`)
- REST route handlers → API or agent client: returns responses
