aegi Conceptual Domain Model

Status

This is the canonical conceptual domain model for the product as it exists in the repository in August 2026.

It describes product meaning, ownership, containment, context, handoffs, and surface projections. It is deliberately above the database schema and below the marketing narrative.

Use it to answer:

• what the product fundamentally models
• which concept is the durable business root
• which records can contain or organize other records
• which relationships are required, optional, or workflow-derived
• which surfaces own truth and which only project it
• whether a new feature strengthens or fragments the product model

Read it with:

• client-operating-model.md
• cross-feature-link-matrix.md
• workflow-completeness-contract.md
• logic-rules.md

Core Thesis

aegi models the work between a service business and its clients as a connected operating graph.

The hierarchy begins with two roots at different levels:

1. The organization is the tenant, authority, and operating business.
2. The client account is the durable business context for client work.

Every major client-work record belongs to a client account. Some records also create a narrower context that organizes related work. A project is the most important secondary context, but it is not the only container and it is never a global prerequisite.

The product therefore follows this shape:

Organization
├── staff, policy, configuration, integrations, and organization operations
└── Client account                          durable client-work context
    ├── relationship and people
    ├── Project                             delivery container
    │   ├── task                            work container
    │   ├── update
    │   ├── blocker
    │   └── optional project context on time, files, notes, and commerce
    ├── collaboration
    │   ├── Drive item                      artifact container
    │   ├── File request                    request/response container
    │   └── Communication thread            conversation container
    ├── commercial records
    │   ├── Quote                           offer and handoff context
    │   ├── Contract                        agreement container
    │   ├── Invoice                         charge and settlement container
    │   └── Subscription                    recurring-service context
    ├── people and access
    │   ├── client contact
    │   └── portal access grant
    └── client-scoped notes, links, reminders, responses, and activity

This is not a strict tree at runtime. It is an ownership hierarchy with a small, controlled set of cross-feature connections.

Conceptual Vocabulary

Root context

A root context answers, "Whose world does this record belong to?"

• organization is the tenancy and authority root.
• client account is the business root for client work.

Aggregate or container

A container gives smaller records a coherent lifecycle and operating context.

Examples:

• a project contains delivery work
• a task contains client actions, conversation, and internal context
• a contract contains contract-owned content and attachments
• a Drive item may contain child items and an asset or rich-document payload
• a file request contains one request/response lifecycle
• a communication thread contains messages
• an invoice contains invoice events and time allocations

"Contains" is conceptual. It may be implemented with a direct ID, a scoped record, or a provider-backed relationship.

Direct client-owned record

A direct client-owned record is valid with only a client account and does not need another product feature to exist.

Examples:

• project
• time entry
• quote
• contract
• invoice
• subscription
• Drive item
• file request
• client link
• communication thread

Optional context

Optional context makes a record easier to understand, retrieve, or report on without changing its primary owner.

Examples:

• a time entry may reference a project, task, or note
• a Drive item may reference a project
• a contract, quote, invoice, or subscription may reference a project
• a note may reference a client or project

Removing optional context must not delete either record or invalidate the owning workflow.

Workflow handoff

A handoff records that one workflow informed or produced another while both records keep their own meaning and lifecycle.

Examples:

• an accepted quote may lead to a contract, invoice, or subscription
• approved time may be allocated to an invoice
• a client work request may be converted into a project task or project
• a task client action may create a linked file request
• a submitted file request may produce a Drive item

Projection

A projection presents or routes existing truth without becoming its owner.

Examples:

• the portal projects authorized client, project, billing, and collaboration truth
• Today projects actionable work from several feature workflows
• Inbox projects personal delivery/read state over shared communication threads
• Overview and Analytics project status, interventions, and derived measures
• Search projects authorized records into a retrieval index

The Current Product Model

1. Organization and staff authority

The organization is the tenant and service business operating aegi.

It owns:

• staff memberships, invitations, roles, and capability policy
• staff client-access mode and selected-client assignments
• branding, domains, senders, API credentials, webhooks, exports, and audit logs
• the connected Stripe account and organization-level billing operations
• catalog products and prices
• organization preferences and analytics configuration

These are organization operations, not client work.

Current implementation concepts:

• organizations
• orgUsers
• orgInvites
• orgRolePolicies
• clientAccessAssignments
• organizationStripeConnections
• billingCatalogProducts
• billingCatalogPrices

2. Client relationship

The client account is the durable context for the relationship between the organization and one client company.

It owns or anchors:

• identity, lifecycle, locale, timezone, and relationship ownership
• billing identity and client-level pricing defaults
• client contacts and agency relationship contacts
• staff visibility assignments
• portal policy and company access grants
• projects and delivery work
• time and working context
• quotes, contracts, invoices, and subscriptions
• Files, requests, links, communications, and client-safe activity

The client account does not need a project, invoice, Drive folder, or portal identity in order to exist.

Current implementation concept: clientAccounts.

3. People and access

The model intentionally separates company people, login identity, and company authorization.

Concept	Meaning	Primary context
Client contact	A human inside one client company	Client account
Portal user	An external login identity inside one organization tenant	Organization
Portal access grant	Authorization connecting one portal user to one client contact and client account	Client account
Portal invite	Pending access lifecycle that may produce or update a grant	Organization plus optional client/contact
Agency relationship contact	An organization staff member presented in a client relationship role	Client account
Staff client assignment	An agency-side visibility grant for selected-client staff	Organization and client account

A portal identity is not the client and does not own client business records. One portal identity may hold grants to multiple client companies inside the same organization.

4. Project and delivery

The project is the strongest secondary context in the client graph. It organizes delivery, but it does not replace the client account and is not required by commercial or collaboration workflows.

A project owns:

• lifecycle, dates, visibility, owner, and team
• delivery pricing treatment for project-linked time
• tasks and subtasks
• project updates
• blockers
• task context, task conversation, and task client actions

A project may provide context for:

• time entries and timers
• notes and links
• Drive items and file requests
• quotes, contracts, invoices, and subscriptions
• portal work requests and client feedback

Task aggregate

A task is the source of truth for a delivery outcome.

It contains:

• subtasks through a parent-task relationship
• client actions requesting a file, content, answer, approval, or action
• contextual messages and mentions
• internal task notes and links

A task may link to:

• time entries
• a source client work request
• a legacy blocker projection
• a file request created for a file-type client action

Current implementation concepts:

• projects
• projectTasks
• projectTaskClientActions
• projectTaskMessages
• projectTaskContextItems
• projectUpdates
• projectBlockers

5. Time and working memory

Time is a direct client-owned work record with optional delivery context.

A time entry:

• always belongs to an organization, staff user, and client account
• may reference a project, task, subscription, or note
• carries captured pricing context so historical work is not silently repriced
• moves through draft, submitted, returned, and approved states
• may be reserved and allocated exactly once into invoice work

An active timer is the transient working counterpart that later creates or updates a time entry.

Notes and reminders are organization working-memory records:

• a note may be personal, client-scoped, or project-scoped
• a reminder may point to several typed product records or an external link
• neither becomes the owner of the records it references

Current implementation concepts:

• timeEntries
• activeTimers
• timeEntryInvoiceAllocations
• notes
• reminders

6. Collaboration and Files

Files is the collaboration domain for general shared material, authored docs, folder organization, retrieval, file exchange, and request fulfillment.

Drive item aggregate

A Drive item always belongs to a client account and may belong to a project.

It may represent:

• a folder containing other Drive items
• a file with one storage-backed file asset
• a rich document with one structured document payload

It may also have:

• visibility and source-side provenance
• a public or controlled share
• an external contributor access link
• external upload submissions

File request aggregate

A file request always belongs to a client account and may reference a project, task, client action, destination folder, and submitted Drive item.

Its lifecycle is:

requested -> submitted -> reviewed -> acknowledged -> closed

The file request owns the request/response lifecycle. The resulting file or doc is owned by its Drive item.

Feature-owned attachments

Shared storage infrastructure does not make Files the business owner of every artifact:

• contracts own contract attachments
• Stripe and billing surfaces own invoice and payment artifacts
• Drive owns general client/project collaboration artifacts

Current implementation concepts:

• driveItems
• fileAssets
• richDocuments
• driveFileShares
• fileRequests
• driveAccessLinks
• driveExternalUploadSubmissions
• contractAttachments

7. Communications, responses, and intake

Communication is source-linked conversation, not a second work-management system.

A communication thread:

• belongs to a client account
• may carry project context
• points to one source workflow through a typed source and source identifier
• contains messages from the organization or client side
• projects into personal Inbox records for participants

Client-authored input uses several typed records because the workflows differ:

• task client actions handle requests attached to delivery work
• file requests handle uploads/docs and review provenance
• portal context requests handle support, new work, and project intake
• client portal responses handle acknowledgment, approval, change requests, and feedback on a project update, Drive item, or contract

These are related collaboration concepts but not interchangeable statuses.

Current implementation concepts:

• communicationThreads
• communicationMessages
• notificationInbox
• portalContextRequests
• portalContextRequestMessages
• clientPortalResponses

8. Commercial spine

The commercial domain has four distinct client-owned records.

Record	Product meaning	Provider truth
Quote	Offer, pricing intent, and possible handoff	Stripe quote state
Contract	Legal commitment, authored terms, and contract-owned attachments	aegi contract state and stored content
Invoice	One-time amount due, settlement, adjustments, and payment outcome	Stripe invoice/payment state
Subscription	Recurring service and billing lifecycle	Stripe subscription state

All four always belong to a client account. All four may carry optional project context. None requires another commercial record to exist.

Billing profile

The client billing profile is the internal mapping between the client account and the connected organization's Stripe customer. It is infrastructure for the commercial domain, not a user-facing commercial record or finance ledger.

Commercial handoffs

Valid handoffs include:

• quote to contract
• quote to invoice
• quote to subscription
• subscription to generated invoice
• approved time to invoice allocation
• invoice to payment, credit, refund, or uncollectible event

Handoffs preserve the identity and lifecycle of every resulting record.

Current implementation concepts:

• clientBillingProfiles
• quoteRecords
• contracts
• invoiceRecords
• invoiceRecordEvents
• subscriptionRecords
• timeEntryInvoiceAllocations

9. Portal projection

The portal is an authorized client-facing projection of the same client graph. It is not a separate business model.

Through an active portal access grant, a portal user may see or act on selected:

• client profile and people
• client-visible projects, tasks, blockers, and updates
• requests, responses, conversation, and shared files
• quotes, contracts, invoices, subscriptions, and hosted provider actions
• activity and settings appropriate to the grant

The portal may create collaboration and access records, such as responses, requests, messages, uploads, invitations, or grant changes. It must not create alternate portal-owned versions of projects, contracts, invoices, subscriptions, or Drive items.

10. Operational projections

The following are views over the domain model rather than ownership domains:

Projection	Job
Client detail	Consolidated view of one client's complete operating context
Top-level workspaces	Cross-client operational views over one record family
Today	Typed execution queue across tasks and operational workflows
Inbox	Personal communication delivery/read projection
Overview	Agency-level prioritization and intervention view
Search	Authorized cross-feature retrieval
Analytics	Derived delivery, finance, collaboration, and team reporting
Activity	Timeline projection of meaningful domain events
Notifications	Personal delivery of domain events and actions

These projections must preserve the exact causal record and destination. They must not create competing statuses or become the only place a workflow can be completed.

Container and Ownership Catalog

Container or root	Directly owns or contains	May contextualize or link	Must not become
Organization	Staff membership, policy, configuration, integrations, audit, catalog	Every tenant-scoped record	A client relationship
Client account	Contacts, projects, commercial records, Drive items, requests, time, links, grants, communication	All client work	A project or billing record
Project	Tasks, updates, blockers	Time, notes, links, Drive items, requests, commercial records	A prerequisite for all client work
Task	Subtasks, client actions, task messages, internal context	Time and file requests	A duplicate project or generic ticket universe
Drive item	Child Drive items and file/doc payload	Project and request context	Owner of commercial/legal artifacts
File request	Request/response lifecycle	Task, client action, folder, resulting Drive item	The only way clients upload files
Contract	Authored agreement and contract attachments	Quote and project context	A Drive item
Invoice	Invoice events and time allocations	Quote, contract, subscription, and project context	The source of finance truth independent of Stripe
Communication thread	Messages and participant projections	One source workflow and optional project	A duplicate task/request system
Portal context request	Request messages and conversion provenance	Client and optional project	A parallel project before acceptance

Relationship Grammar

Every new relationship must use one of these meanings.

Relationship	Meaning	Example
Tenant scope	Which organization has authority	Project -> organization
Required client ownership	Which client relationship owns the record	Invoice -> client account
Primary containment	Which aggregate owns the child lifecycle	Task message -> task
Optional context	A useful removable association	Contract -> project
Workflow handoff	One workflow informed or produced another	Quote -> invoice
Projection	A surface presents existing truth	Portal -> invoice state
Provider mapping	aegi attaches operating context to external truth	Invoice record -> Stripe invoice

A relationship is invalid when its only justification is that two records can technically reference each other.

Surface Model

The domain model is projected through three product surfaces.

Organization surface

• operating workspace for staff
• client detail is the consolidated home for one client's graph
• top-level workspaces are advanced cross-client projections
• settings and organization operations remain outside the client graph

Portal surface

• tenant-host-selected client-facing runtime
• grant-selected access to one client company at a time
• client-safe view and action layer over shared truth
• separate identity realm from organization staff

Platform surface

• aegi operator control plane
• owns platform users, audit, assets, incidents, and recovery operations
• does not participate in normal client-work ownership

Domain Invariants

The model is coherent only while all of these remain true.

1. Organization is the tenant and authority boundary.
2. Client account is the required business root for major client work.
3. Every client-work record can resolve its client account directly or through its primary owner.
4. Every record has one clear primary owner, even when it has several context links.
5. Project is a strong optional secondary context, not a universal prerequisite.
6. Delivery, commercial, and collaboration states remain typed and independent.
7. Optional links never silently change ownership, money, access, or visibility.
8. Workflow handoffs preserve the records and provenance on both sides.
9. Feature-owned artifacts remain with their business workflow even when they share storage infrastructure.
10. Portal records authorize or collaborate around org truth; they do not fork the business model.
11. Today, Inbox, Search, Overview, Analytics, Activity, and Notifications are projections and routing layers, not record owners.
12. Stripe remains authoritative for provider finance state while aegi owns the client and service operating context.
13. Internal and client-visible information use explicit policy and must never be inferred from the surface that happens to render it.
14. Any item claiming to need action preserves its cause, actor, state, valid action, exact destination, permission result, and completion condition.

Deliberate Exceptions to the Client Root

Not everything in the application is client work.

Valid non-client records include:

• organization settings, staff access, audit, integrations, and catalog
• personal notes and reminders without client context
• authentication, MFA, security, and impersonation records
• platform administration, assets, incidents, and recovery
• marketing subscribers, blog content, campaigns, and signup access
• provider webhook, repair, reconciliation, and organization-finance operations before or outside client mapping

These records must not be forced under a fake client merely to make the diagram look uniform.

Current Implementation Alignment

The live model already satisfies the main architecture:

• projects, time, contracts, quotes, invoices, subscriptions, Drive items, file requests, communication threads, and portal grants all carry client ownership
• project context is optional for time, collaboration, and commercial records
• project tasks and collaboration records preserve the client ID even when a stronger parent exists, supporting authorization and cross-client views
• portal writes collaborate around or authorize existing truth instead of creating alternate business records
• contract attachments remain contract-owned
• Stripe-backed records mirror provider truth while preserving client context
• Today, Inbox, Search, Analytics, and client/top-level workspaces operate as projections

Implementation Seams to Scrutinize

These are not conclusions that the model is wrong. They are the places where the implementation currently carries the most conceptual risk.

1. Client identity duplication. clientAccounts still carries convenience primary-contact fields while clientContacts is the canonical company people list. The write/read contract must prevent those representations from drifting.
2. Billing-profile circularity. The client account optionally references its billing profile while the billing profile requires the client account. The lifecycle must keep the pair one-to-one and repairable.
3. Generic source references. Communication threads, reminders, portal responses, and notification metadata use typed strings or hrefs for some cross-feature targets. Product contracts and tests carry integrity that the schema cannot enforce directly.
4. Commercial provenance rollout. Quote revisions and quote-to-contract/invoice/subscription handoffs now retain optional direct app-record IDs while Stripe identifiers remain provider reconciliation identity. New webhook writes populate both forms, readers prefer local IDs, and billing/migrations.ts backfills compatible legacy rows. These links remain optional because standalone and externally created billing records legitimately have no originating quote.
5. Project-file dual meaning. A project is the business context for project files while Drive owns their storage/retrieval record. Product language must preserve both truths without implying duplicate files.
6. Client-action/file-request pairing. The task client action and file request point to one another. Creation, repair, and lifecycle code must preserve a one-to-one paired workflow without partial links.
7. Client feedback follow-through. Portal responses can now retain typed, client-validated task, project-update, and organization-reply outcomes. The remaining seam is interaction-level: handling surfaces must capture and display those outcomes instead of marking consequential feedback handled without them.
8. Distributed activity truth. Activity is derived from several domain records and specialized event tables rather than one universal event ledger. That is acceptable only while projections preserve causal record identity.
9. Optional client context on portal intake. Portal context requests permit a missing client account at the schema level. Runtime grant resolution must ensure client-originated work remains attributable to the correct company whenever the workflow is client work.
10. Legacy conceptual residue. Older documents referenced an Engagement entity and a generic Document model. Neither is part of the current live domain. Service context now lives across the client, project, contract, quote, and subscription records; Files runs through Drive items.

Change Rule

Before adding a new first-class entity, answer all of these:

1. Is it organization-level, client-owned, or a deliberate non-client exception?
2. What is its one primary owner?
3. Is it a container, a child record, an optional context link, a workflow handoff, or a projection?
4. Can it exist without a project?
5. Is it internal, client-visible, or policy-dependent?
6. What record owns its lifecycle and terminal state?
7. What exact surface completes its workflow?
8. Does an external provider own any part of its truth?
9. Could an existing entity express the concept without losing meaning?
10. Does the change preserve every invariant above?

If those answers are not clear, the product concept is not ready to enter the schema or navigation.