Appearance
Data model
DutyGraph records a company as typed, versioned records in PostgreSQL. This page explains the main entities in plain English. It describes concepts, not every column.
The core picture
mermaid
flowchart TB
T["Tenant<br/>advisor workspace"] --> CO["Company"]
T --> ACC["Account"] --> ENG["Engagement"] --> CO
CO --> P["Person"]
P -.->|role and team| R["Role / Department<br/>derived"]
P -->|owns| D["Duty"]
D -->|groups| TC["Task Card"]
P -->|"owns / performs"| TC
TC -->|handoff| TC2["Task Card"]
WF["Workflow"] -->|orders| TC
REQ["Ask"] --> RES["Answer"] --> EV["Evidence"]
EV --> TC
CL["Research claim"] --> CO
TC --> PC["Possible constraint"] --> MEA["Measure"] --> OUT["Outcome"]
TC --> M["Agent manifest"] --> AR["Agent request"]
AR --> LE["Ledger entry"]
AR --> IA["Issued agent"] --> AA["Agent activity"]
GP["Governance packs<br/>rules, catalog, holdings, chain"] --> ARCompany and engagement
| Entity | What it is |
|---|---|
| Tenant | An advisor's workspace or firm. Every business row carries its tenant. |
| Account | A company in the advisor's pipeline, with its contacts and timeline |
| Company | The organization being mapped. A sample company is marked as a sample. |
| Engagement | The advisor's piece of work with the company. Its status runs from proposed to active, paused, complete or cancelled. An active engagement needs a recorded activation, such as a payment. A separate engagement record holds the scope, dates, systems and success criteria. |
People and work
| Entity | What it is |
|---|---|
| Person | Name, email, role, team and manager. Reporting lines come only from recorded managers. |
| Role and Department | Derived from people's roles and teams. They are marked Inferred and get readable ids such as DEPT-FINANCE. |
| Duty | A lasting responsibility with one owner. It groups Task Cards. |
| Task Card | One bounded piece of work: purpose, trigger, inputs, steps marked [H], [A] or [S], outputs, systems, an owner, a performer and a proposed AI mode. See Task Cards. |
| Handoff | A recorded link from one Task Card's output to another's input. It must connect two different Task Cards. A handoff marked as executable, not documentation only, needs an exception owner. |
| Workflow (flow) | An ordered set of Task Cards and handoffs. DutyGraph refuses cycles, duplicate paths and disconnected steps. |
Duty ownership, reporting lines and Task Card confirmation are separate facts. One never implies another.
Asks, answers and evidence
| Entity | What it is |
|---|---|
| Ask (request) | Questions sent to one person, by email or private link |
| Answer (response) | What the person sent back, kept with the understanding they confirmed |
| Confirmation | A person's decision on an exact version of a record: correct, needs change, not mine or unsure |
| Evidence | An original source: an accepted answer, meeting notes, a reviewed transcript or a research page. It is labelled Known, Inferred, Assumed or Missing. Retracting it keeps its history and marks dependent records stale. |
| Research claim | One researched fact, such as headcount. It holds a value, a state (known, inferred, disputed or unknown), a confidence and a verification state, such as client confirmed or corrected. Each change is a new claim version. |
| Field reading | A value DutyGraph read from an answer, pointing to the speaker's own words. It waits in Repo › To review until the advisor accepts it. |
How these become file states is on Evidence and provenance.
Repo files
A Repo file is not stored. The compiler builds it from the records above. See System architecture. Two things are stored for files:
- Notes: append-only text versions for a file, saved only when the advisor accepts a DutyGraph Agent edit that fits no record field.
- Stable ids. Every file has an id that never changes. A record-backed file uses a prefix and eight hex characters, in the form
TSK-1a2b3c4d. Prefixes includeCOMPANY,DEPT,ROLE,PER,DUTY,TSK,FLOW,HND,AGT,MET,SYSandFND.
A link between files is an id in double square brackets, such as [[ROOT-AGENTS]]. An id that does not resolve is shown as plain text. Links up, down and across the company are computed from records, never typed. A link is confirmed only when accepted records state it, and proposed otherwise.
Improvement records
| Entity | What it is |
|---|---|
| Possible constraint | A hypothesis about what limits a flow, with quotes from Repo files. It is never shown as proven. |
| Measure | A metric with an owner, a formula, a unit, a baseline and a target. A missing baseline needs a reason. Readings are added over time. |
| Change (intervention) | A change to test against a possible constraint, with an owner, a measure, a prediction, stop conditions and a review date. Route's Accept writes one. |
| Outcome | The result of a change: supported, falsified or inconclusive, with its evidence. It keeps the original prediction. A falsified result reopens the hypothesis. |
| Task proposal | An AI mode, owner, performer or hours value that code proposed for a Task Card, waiting for Accept |
Agents and governance
| Entity | What it is |
|---|---|
| Agent manifest | A versioned, hashed description of one agent for one named person. See Agent builder and manifests. |
| Agent plan link | A frozen copy of a manifest version and hash, shared with the person by a private link |
| Agent request | A request to issue an agent, for named Task Cards, with each scope's state (Inherited, Auto-trimmed or Escalated) and the approval chain's decisions. It records Task Card ids, not Task Card versions. |
| Governance packs | Six kinds, each versioned with a content hash: agent rules, separation of duties (SoD) rules, mitigating controls, the System Catalog, holdings and the approval chain. A new load is a new version that supersedes the old one. |
| Task Card registry entry | A governance id (TSK-0001) for an eligible Task Card, with the scopes it is treated as needing: its listed scope lines, else every catalog scope of its systems |
| Holdings | The access each person holds, as system/action:object scopes, from an uploaded access export. Matched by email or external id, never by name. Never compiled into the Repo. |
| Ledger entry | One governance event: a pack sealed, a request decided, an agent issued, suspended or revoked. Each entry holds the hash of the previous one. See Ledger. |
| Issued agent and credential | The agent as issued, with its issued scopes, bound to its manifest hash, its issue record and its expiry. The credential is stored only as a hash. |
| Agent activity | One row per gateway call: agent, tool, scope, allowed or blocked, and the rule for a block |
Work, capability and authority
Some of the distinctions below are built. The rest are proposed refinements, marked Planned. They would extend the existing Task Card records, governance packs and evaluator, not add a separate authorization database.
| Concept | What it is | Status |
|---|---|---|
| Task definition | What the work is: purpose, trigger, steps, systems, rules | Built, as the Task Card. Definition and assignment share one record today. |
| Task assignment | Who owns and who performs the work | Built as owner and performer fields on the Task Card. A separate assignment record, so one definition can have many assignments, is Planned. |
| Business capability | An action the work requires, named in business terms, for example "place a hold on a supplier invoice", referenced from a Task Card step | Planned |
| Entitlement | A permission in a system. Today a catalog scope, or an entitlement name in an access export that the catalog maps to scopes. | Built as scopes and catalog mappings. Capability-to-entitlement mappings validated by an application owner are Planned. |
| Agent Grant | The authority issued to one agent under conditions: scopes, controls, end date | Built as the issued agent's scopes and credential. A grant traced to validated capabilities is Planned. |
| Versions | Each mapping and grant records its source, evidence, version, validator, confirmation state and effective period | Partial: records, packs and manifests are versioned and hashed. Requests pinning Task Card versions, and versioned mappings, are Planned. |
The Agent Authority Record is a Planned view over these records. It is not new storage.
Versions and content hashes
- Every change to a record is a new version. The application cannot change or delete an earlier version.
- Each version has a content hash over its canonical JSON plus the tenant, company, record id, kind, title and version.
- A confirmation binds one version and hash. If the work changes, the person confirms again.
- A state change is an audit event, not a new version. A hash identifies content, not each later review step.
- Governance packs, the ledger and agent activity are append-only.
INFO
Status. Built: every entity on this page not marked Planned, versioned records with content hashes, confirmations bound to a version, stable Repo ids and [[ID]] links, append-only Notes, governance packs, the hash-linked ledger and agent activity. Simulated: holdings and identity data in the governance sample come from illustrative files. Planned: role and department records of their own (today they are derived), separate task assignments, business capabilities, validated entitlement mappings, Task Card version pins on requests, and live holdings from identity systems.
Source: gitbook/product/architecture/data-model.md in the DutyGraph repository.