WorkTruck’s shape is small on purpose. Every operation an agent performs maps cleanly onto eight entity types and one universal relationships table.Documentation Index
Fetch the complete documentation index at: https://docs.worktruck.app/llms.txt
Use this file to discover all available pages before exploring further.
The eight entities
| Entity | What it is | Temporal class |
|---|---|---|
| People | Individual humans or agents the tenant interacts with. Holds display name, channels (email/phone), tags. | Bitemporal |
| Organizations | Companies, households, groups. Has locations and members. | Bitemporal |
| Tasks | Discrete units of work. Title, status, owner, due date, priority. Can be assigned to a Person. | Unitemporal |
| Notes | Free-form text. Tagged, optionally pinned/archived. Comment-style attachments to other entities. | Bitemporal |
| Events | Calendar entries — appointments, deadlines, scheduled syncs. Supports attendees + RRULE recurrence. | Type 0 (no history) |
| Messages | Communication threads — email, calls, meetings logged after the fact. | Type 0 (no history) |
| Files | Binary/document attachments stored via a pluggable backend. | Type 1 (no history) |
| Relationships | Typed edges between any two entities. The universal join table. | Event-log |
Temporal classes
WorkTruck tracks history at four different fidelities:- Bitemporal (People, Organizations, Notes) — both valid-time and system-time tracked. Every edit writes a history row; “what did this person look like on Tuesday at 3pm” is answerable.
- Unitemporal (Tasks) — valid-time only. History rows on every edit; system-time of the edit isn’t preserved.
- Type 0 (Events, Messages) — no history. Designed for high-volume streams where the cost of full history would dominate the table.
- Event-log (Relationships) — insert-only. Updates and deletes are recorded as new rows with a kind discriminator.
docs/schema-review/temporal.md for the rationale.
Relationships are first-class
Almost every meaningful connection in WorkTruck is a row in therelationships table — Person attends Event, Note is about Task, File attached to Message, Organization employs Person. The relationship’s relationship_type field is a typed enum; the matrix of which (from-entity-type, to-entity-type, relationship_type) tuples are allowed lives in internal/relationships/matrix.go as the authority, with a Postgres CHECK constraint as defense-in-depth.
Agents query relationships in either direction — “all tasks about this Person”, “all Files attached to this Message” — without needing to know the underlying join.
Two write paths: API and worker
Agents write to WorkTruck two ways:- Synchronous via HTTP / MCP / CLI — direct CRUD. Fast, immediate, used by the dashboard and ad-hoc operator tooling.
- Asynchronous via the worker — reconciler jobs (email → person, message → thread), scheduled agent runs, retention/cleanup. Worker is river-backed; jobs are durable.