---
url: /handbook/architecture/system-architecture.md
description: >-
  DutyGraph's components and trust boundaries, the three entry points into one
  model, the path from discovery to authority, the Company Repo, tenancy, the
  MCP surfaces and hosting.
---

# System architecture

DutyGraph is a single-origin web application: a React browser app and one Express API server in front of one PostgreSQL database. This page shows how the parts connect, how work becomes authority, and where each trust boundary sits.

## Components

```mermaid
flowchart LR
    subgraph Browser
        APP["Advisor app"]
        LINK["Private link pages<br/>sponsor, team, agent plan"]
    end
    PHONE["Companion phone app"] --> API
    APP --> API["Express API server"]
    LINK --> API
    MCPC["AI chat or tool"] -->|"/api/mcp"| API
    AGENT["Issued agent"] -->|"/api/mcp/agent"| GW["Gateway check"] --> API
    API --> PG[("PostgreSQL")]
    PG --> OUT["Outbox"] --> PROJ["Graph projection<br/>in PostgreSQL"]
    PROJ -.-> NEO[("Neo4j Aura<br/>optional copy")]
    PG --> COMP["Repo compiler"] --> FILES["Company Repo files"]
    API --> JOBS["Provider jobs<br/>AI, research, email"]
    CRON["Maintenance run<br/>every 5 minutes"] --> API
```

| Component | Job | Boundary |
| --- | --- | --- |
| **Browser app** | Screens for advisors and company members | Holds no authority. The server checks every action. |
| **Private link pages** | Sponsor packet, team asks, kickoff pre-read, agent plan | Each action is limited to that one link. A link proves only that someone has it. |
| **Companion phone app** | Team members answer asks on a phone | Another client of the same API and records |
| **API server** | Sign-in, permissions, commands, reads and jobs | The only path to the database |
| **PostgreSQL** | The record | Authoritative |
| **Repo compiler** | Turns records into the Company Repo | Pure code with no writes |
| **Graph projection** | Record metadata and recorded links for graph views | Derived. It can lag; it never rewrites the record. |
| **Provider jobs** | Calls to AI, research and email providers | Run outside database transactions, with recorded attempts |

## Three entry points, one model

DutyGraph has one discovery and evidence engine and one canonical operating model. Three workflows can populate it. They are not three products, and they do not keep separate databases or Task Card formats. Each sets the starting scope, the sponsor, the people involved, the evidence required and the approvals needed.

| Entry point | Starts from | Status |
| --- | --- | --- |
| **Top-down discovery** | Sponsor and executive priorities, down to departments, managers, employees and tasks | **Built**, designed around a functional organization |
| **Pod-down discovery** | One department head and a bounded unit, recording links to other departments without a full company map | **Planned** |
| **Bottom-up governance trigger** | An employee's agent request. If no confirmed Task Card fits, a short capture of that task. | **Partial**: request tools Built; the capture, manager confirmation and application-owner validation are Planned |

See [Three ways in](../start-here/three-ways-in.md).

## From discovery to authority

```mermaid
flowchart LR
    SRC["Research, asks,<br/>interviews, kickoff"] --> EV["Evidence<br/>and confirmations"]
    EV --> TC["Task Cards<br/>and steps"]
    TC -.->|"Planned"| CAP["Business<br/>capabilities"]
    CAP -.->|"Planned: app owner validates"| ENT["Technical<br/>entitlements"]
    TC -->|"today: coarse scope list"| EVAL{"Evaluator"}
    ENT -.-> EVAL
    HOLD["Holdings<br/>access export"] --> EVAL
    RULES["Rule packs<br/>and SoD"] --> EVAL
    EVAL --> APPR["Approval chain"]
    APPR --> LED["Ledger<br/>decision and evidence"]
    LED -.->|"Planned: Decision Export"| IAM["Customer IAM<br/>provisions"]
    IAM -.->|"Planned: Event Import"| LED
    LED --> GWY["Optional gateway<br/>checks routed calls"]
    GWY --> ACT["Activity record"]
```

* **Task → capability → entitlement.** Today a Task Card's needed scopes are the scope lines it lists, or every catalog scope of its systems. Mapping steps to business capabilities, and capabilities to entitlements validated by the application owner, is **Planned**. See [The key join](../governance/the-key-join.md).
* **The governance decision and evidence layer.** The evaluator, the approval chain and the hash-linked ledger record what was decided and why. **Built**.
* **External IAM integrations.** Decision Export to the company's IAM or IT service management, and Event Import back, are **Planned**. No live identity connection exists today.
* **The optional runtime gateway.** It checks calls an issued agent routes through it. **Built**, for routed calls only.
* **Lifecycle revalidation.** Manifest freshness, stale-decision refusal, revocation and expiry are **Built**. Recomputing grants when holdings or Task Cards change is **Planned**. See [Approval, provisioning and revalidation](../governance/approval-provisioning-and-revalidation.md).

## Trust boundaries

| Who | Decides or does | Does not |
| --- | --- | --- |
| **DutyGraph** | Records evidence, proposes scopes, routes the approval chain, records decisions on the ledger | Provision identities or change access in business systems |
| **The company's approvers** | Decide each step of a request | Act through chat. Decision routes refuse MCP calls. |
| **The company's IAM** | Creates the agent identity and grants access | Report back to DutyGraph today. Event Import is Planned. |
| **Runtimes** | Run the agent and apply their own settings, such as ask-first | Prove to DutyGraph that a setting is applied |
| **Target systems** | Allow or refuse each action against real access | Share their logs with DutyGraph today |
| **DutyGraph gateway** | Allows or blocks calls routed through it | See calls made any other way, or ask a person before a single call |

## The path of a request

```mermaid
sequenceDiagram
    participant U as Browser
    participant S as API server
    participant D as PostgreSQL
    U->>S: Command with session cookie, CSRF token, Idempotency-Key
    S->>S: Resolve the signed-in user, tenant and company access
    S->>D: Begin transaction, set the tenant for this transaction
    S->>D: Check the receipt for this key
    S->>D: Check expected version, write new version, audit event, outbox row
    S->>D: Save the receipt, commit
    S-->>U: Result
```

The session is an HttpOnly cookie, and every signed-in write also needs a cross-site request forgery (CSRF) token. The server works out the tenant and company from the signed-in user, never from the browser. Forced row-level security limits every query to that tenant. A repeat with the same `Idempotency-Key` returns the saved result. A write carries the version it expects, and a conflict stops it. Calls to an AI or research provider happen outside the transaction, after a job row is reserved.

## The Company Repo is compiled, not stored

The [Company Repo](../discovery/company-repo.md) looks like a folder of files, but no file is stored. One pure function reads the company's records and writes the file tree in memory. The same input gives the same files and hashes. One compile feeds the Repo page, the Work Map, **Download your company**, the MCP read tools and the [DutyGraph Agent](../advisors/repo-copilot.md). To change a file, change the record behind it. Holdings are never compiled.

## PostgreSQL is the record, the graph is derived

PostgreSQL holds every company, record, version, confirmation, audit event and governance decision. A transactional outbox feeds a projection of record metadata and recorded links. An advisor account can also connect its own **Neo4j Aura** database, which receives ids, kinds, titles, states, versions, hashes and links, never evidence bodies, audio, prompts or credentials. The app reads Aura only when it matches PostgreSQL. A link exists only when a record states it. Proposed links are marked **Proposed**.

## Tenancy

| Level | What it is |
| --- | --- |
| **Tenant** | An advisor's workspace or firm. The security boundary and the place where provider keys live. |
| **Company** | A client company inside a tenant. References are checked against the same company. |
| **Participant** | A team member bound to one company and one person. They see only their own assigned asks. |

See [Security and data handling](../trust/security-and-data.md).

## MCP surfaces

| Surface | Endpoint | Who | Can it decide? |
| --- | --- | --- | --- |
| **Advisor MCP** | `/api/mcp` | An advisor's AI tool, with a scoped personal token | No governance decisions |
| **Employee request tools** | `/api/mcp` | An employee's own AI chat, with a token bound to one person | No. It can request and check status. |
| **Agent gateway** | `/api/mcp/agent` | An issued agent, with its own credential | It allows or blocks each routed call |

The gateway checks status, expiry, issued scopes and the tool-to-scope match, and records the outcome. It has no per-call human approval step. See [Agent gateway](../governance/agent-gateway.md).

## Hosting

The hosted service runs on Vercel in the US East (IAD1) region, with a dedicated Neon PostgreSQL database. The app connects with a restricted role that cannot bypass row-level security. A protected maintenance run every five minutes drives notifications, the graph projection, retention and scheduled research.

::: info
**Status.** **Built**: the browser app, the Express API, PostgreSQL with forced row-level security, idempotent and version-checked commands, the compiled Company Repo, the graph projection and optional Neo4j Aura copy, top-down discovery, the three MCP surfaces, the evaluator, approval chain, ledger and gateway check, and Vercel hosting. **Partial**: the bottom-up trigger and task-based justification. **Simulated**: the business systems behind the gateway in the governance sample. **Planned**: pod-down discovery, step-level capabilities and validated entitlements, Decision Export and Event Import, broad revalidation, OAuth sign-in on the MCP server, enterprise single sign-on, distributed workers and pagination for very large companies.
:::
