Skip to content

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
ComponentJobBoundary
Browser appScreens for advisors and company membersHolds no authority. The server checks every action.
Private link pagesSponsor packet, team asks, kickoff pre-read, agent planEach action is limited to that one link. A link proves only that someone has it.
Companion phone appTeam members answer asks on a phoneAnother client of the same API and records
API serverSign-in, permissions, commands, reads and jobsThe only path to the database
PostgreSQLThe recordAuthoritative
Repo compilerTurns records into the Company RepoPure code with no writes
Graph projectionRecord metadata and recorded links for graph viewsDerived. It can lag; it never rewrites the record.
Provider jobsCalls to AI, research and email providersRun 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 pointStarts fromStatus
Top-down discoverySponsor and executive priorities, down to departments, managers, employees and tasksBuilt, designed around a functional organization
Pod-down discoveryOne department head and a bounded unit, recording links to other departments without a full company mapPlanned
Bottom-up governance triggerAn 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.

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.
  • 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.

Trust boundaries ​

WhoDecides or doesDoes not
DutyGraphRecords evidence, proposes scopes, routes the approval chain, records decisions on the ledgerProvision identities or change access in business systems
The company's approversDecide each step of a requestAct through chat. Decision routes refuse MCP calls.
The company's IAMCreates the agent identity and grants accessReport back to DutyGraph today. Event Import is Planned.
RuntimesRun the agent and apply their own settings, such as ask-firstProve to DutyGraph that a setting is applied
Target systemsAllow or refuse each action against real accessShare their logs with DutyGraph today
DutyGraph gatewayAllows or blocks calls routed through itSee 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 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. 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 ​

LevelWhat it is
TenantAn advisor's workspace or firm. The security boundary and the place where provider keys live.
CompanyA client company inside a tenant. References are checked against the same company.
ParticipantA team member bound to one company and one person. They see only their own assigned asks.

See Security and data handling.

MCP surfaces ​

SurfaceEndpointWhoCan it decide?
Advisor MCP/api/mcpAn advisor's AI tool, with a scoped personal tokenNo governance decisions
Employee request tools/api/mcpAn employee's own AI chat, with a token bound to one personNo. It can request and check status.
Agent gateway/api/mcp/agentAn issued agent, with its own credentialIt 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.

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.

Source: gitbook/product/architecture/system-architecture.md in the DutyGraph repository.

DutyGraph. Pages label each feature Built, In review or Planned.