Appearance
Architecture
DutyGraph is one web application with one database of record. Everything else, including the Company Repo, the graph view and every AI proposal, is built from that record or waits for a person to accept it.
The layers
mermaid
flowchart TB
subgraph Clients
B["Browser app<br/>advisor, sponsor and team pages"]
PH["Companion phone app"]
AI["An AI chat or tool<br/>over MCP"]
AG["An issued agent"]
end
B --> API["API server<br/>permissions, commands, jobs"]
PH --> API
AI -->|"/api/mcp"| API
AG -->|"/api/mcp/agent<br/>gateway check"| API
API --> PG[("PostgreSQL<br/>the record")]
PG --> REPO["Company Repo<br/>compiled files"]
PG --> PROJ["Graph projection"]
PROJ -.->|optional copy| NEO[("Neo4j Aura")]
API -->|"proposals only"| LLM["AI providers<br/>the company's approved connection"]| Layer | What it is | What it decides |
|---|---|---|
| Browser app | The advisor's workspace, plus private pages for sponsors, team members and agent plans. It works on a phone. | Nothing. It hides buttons a role cannot use, but the server decides. |
| API server | One Express application. It checks every permission, runs commands and starts AI and research jobs. | Who may read or change what. |
| PostgreSQL | The record: companies, people, duties, Task Cards, evidence, versions, confirmations, audit events, governance packs and the ledger. | It is the only source of truth. |
| Company Repo | The company as files, compiled from PostgreSQL by one function. | Nothing. It is a view. The same records give the same files. |
| Derived graph | A projection of record metadata and recorded links, kept in PostgreSQL, with an optional copy in Neo4j Aura. | Nothing. It never adds a relationship the records do not hold. |
| AI providers | Claude (Anthropic), OpenAI and, for the phone app, xAI. | Nothing. AI output is a proposal until a person accepts it. |
| MCP surfaces | Advisor tools, employee request tools and the agent gateway, over the Model Context Protocol (MCP). | No MCP tool can approve an agent. |
| Gateway | An optional DutyGraph check on calls an issued agent routes through it. | Allows or blocks each routed call against the agent's status, expiry and issued scopes. It does not see calls made another way. |
Five ideas to keep in mind
- One record. PostgreSQL holds the truth. The Repo, the Work Map, exports, MCP reads and the graph are all built from it.
- AI proposes, people decide. AI can save a proposal, but no AI output becomes an accepted record by itself. Permissions, verdicts, the approval chain and the ledger are code.
- Each firm is walled off in the database. Forced row-level security applies to every business table, and the app connects as a role that cannot bypass it.
- History is kept. Records are versioned and hashed. Confirmations bind an exact version. Governance decisions go on a hash-linked ledger. A hash shows a record was not changed, not that its content is true.
- Evidence, approval and enforcement are different. A confirmed answer is evidence, not authority. An approval in DutyGraph is a recorded decision. The company's IAM provisions access, and runtimes and business systems enforce it.
In this section
| Page | What it answers |
|---|---|
| System architecture | The components, the three entry points, the path from discovery to authority, trust boundaries, how the Repo is compiled, tenancy, the MCP surfaces and hosting |
| Data model | The main things DutyGraph records, how they relate, and how versions, hashes and ids work |
| How DutyGraph uses AI | Every place AI is called, every place code decides instead, and the rules both follow |
| The role AI persona | How the persona prompt for a role is built from its approved profile, block by block, and why |
For isolation, secrets, AI data handling and retention, see Trust and security and Security and data handling.
INFO
Status. Built: the browser app, the API server, PostgreSQL as the record, the compiled Company Repo, the graph projection with an optional Neo4j Aura copy, AI calls through approved connections, the three MCP surfaces and the gateway check. Simulated: the business systems behind the gateway and the agent runtime in the governance sample. Planned: OAuth sign-in for web AI connectors, enterprise single sign-on, live identity-system connections, and Decision Export and Event Import with the company's IAM.
Source: gitbook/product/architecture/README.md in the DutyGraph repository.