# Business domain model

This folder captures the **business reality** the app will eventually model.
It's not a description of the current code — none of this is built yet —
but it's the long-term context anyone building this app needs to
internalize.

When in doubt, read this folder before designing a new schema, table,
or feature.

## What's in here

| File | What it covers |
|---|---|
| [people.md](people.md) | The roster of human actors and their roles. |
| [companies.md](companies.md) | The roster of organizations (agencies, clients, intermediaries) and their nature. |
| [relationships.md](relationships.md) | The kinds of working relationships between parties, with a worked example of the worst-case complexity. |
| [projects-and-time-logs.md](projects-and-time-logs.md) | How work is organized into projects + sets, the `{Client} : {Project}` time-log naming convention, and per-party project visibility. |

## How to maintain it

This folder follows the same pruning rule as `features/` — if an entity
goes away (e.g. NewGrowth dissolved into Qualia), update the record
rather than leaving a tombstone. Capture significant model shifts in
`docs/decisions.md`.

The rosters in `people.md` and `companies.md` are *illustrative, not
exhaustive*. Real-world relationships are added or revised as the
business evolves. The patterns documented in `relationships.md` should
be the stable bit.

---

## Terminology recommendations

The original notes used several terms loosely. Below are the terms I
recommend we standardize on across the docs (and eventually the schema).
**Push back on any of these** — they're proposals, not commitments.

### Party (proposed) — replaces "person or company" mixed usage

A unified term for any actor in the system, whether a human or an
organization. A **Party** has subtypes:
- **Person** — a human (Rian, Adi, Heather).
- **Org** — a company / agency / client entity (Bowden Works, PlusROI,
  Tingang, AISV).

Both can be parties to a contract, own projects, send invoices, etc.
A *person* might be the owner of an *org*, and an *org* can act on
behalf of itself or be transparent on behalf of a *person*.

**Why:** the same modeling distinction in Salesforce (Account / Contact),
NetSuite (Entity), and most B2B platforms. Avoids a forest of bespoke
relationships and lets the schema treat "who does work for whom" as a
single relationship table.

### Engagement (proposed) — replaces vague "relationship"

A directional, typed working relationship between two parties for a
specific purpose. Examples:
- Bowden Works ⇄ PlusROI: **profit-share** engagement.
- Adi ⇄ Bowden Works: **subcontractor** engagement, **hourly** comp.
- McAllister ⇄ PlusROI on project X: **subcontractor** engagement.
- McAllister ⇄ PlusROI on project Y: **referrer** engagement (commission).
- AISV ⇄ PlusROI on Community Financials: **referrer** engagement
  (legacy commission, no current visibility).

Two parties can have **multiple concurrent engagements**, scoped
differently (per-project, per-engagement-tier, per-time-period).

**Why:** "relationship" is too vague — it doesn't capture direction,
purpose, or compensation. "Engagement" is the standard term in
agency/professional-services software.

### Engagement type and the roles in it (proposed)

An engagement has a **type** (the pattern of the relationship) and
each side plays a **role**. Same engagement, different role for each
party.

| Engagement type | One side | Other side | Notes |
|---|---|---|---|
| **subcontract** | **Prime** (owns the client relationship) | **Subcontractor** (delivers the work) | When McAllister hires PlusROI to deliver on Copernic, McAllister is Prime, PlusROI is Subcontractor. |
| **referral** | **Referrer** (made the intro, collects commission) | **Operator** (does the work + owns the client) | When AISV sent Community Financials to PlusROI, AISV is Referrer, PlusROI is Operator. |
| **referral-pass-through** | **Referrer-of-Record** (handles client-side billing too) | **Operator** | Legacy McAllister pattern: bills the client, pays through to PlusROI. |
| **partnership** | **Partner** | **Partner** | Symmetric. Bowden Works ↔ PlusROI is the canonical case. Profit/loss is shared per a documented or de-facto split. |
| **freelance** | **Engager** (the party paying) | **Freelancer** (the person/small-org doing the work) | Per-unit, hourly, or fixed-price comp. |
| **direct-client** | **Client** | **Operator** | The end-client engagement on a project. |
| **employment** | **Employer** | **Employee** | Salary or salary-equivalent. Currently unused. |
| **official-partnership** | **Owner** | **Owner** | Documented co-ownership of an org. May or may not include work (Nicole Bowden = no work; Danielle Cooper = bookkeeping). |

**Why "Prime" and "Subcontractor" specifically:** these are the standard
pair in services / agency / construction work. "Prime" makes clear that
this party owns the client relationship and is responsible to the end
client; "Subcontractor" makes clear the work is being delegated. The
pair distinguishes cleanly from **Referrer**, who didn't take on the
work at all — they just made the intro.

A given engagement carries one type but can shift over time. McAllister
on a single client is sometimes a Prime (subcontracting work to PlusROI)
and sometimes a Referrer (just collecting commission). That's two
distinct engagements between the same parties — same project, different
type. The system should model engagements as the unit, not "the
McAllister/PlusROI relationship" as a whole.

### Compensation model (proposed)

Separate from engagement type because the same engagement type can have
different comp:

- **per-unit** — units of work assigned, fixed value per unit.
- **hourly** — billed by tracked time.
- **fixed-price** — a price agreed up front for a defined scope.
- **profit-share** — percentage of net revenue after expenses.
- **commission** — percentage of gross revenue paid to a referrer.
- **gross-percentage** — percentage of gross revenue paid (Danielle's
  PlusROI bookkeeping comp).
- **salary** — fixed periodic comp (employees only).

The current Clockify-to-Toggl flow only models **hourly** for Adi (with
proportion-based markup) and **per-unit** for PlusROI freelancers.

### Visibility level (proposed)

When more than one party touches a project, each may have a different
level of insight. Proposed levels:

- **operator** — does the work, sees everything.
- **subcontractor-deep** — sees scope, team, tasks, schedule, but not
  the operator's internal cost breakdown.
- **subcontractor-shallow** — sees scope and high-level status only.
- **referrer-billing** — sees engagement size, payments, their commission.
- **referrer-blind** — knows the engagement exists, sees only
  commission settlements.
- **client** — sees what the operator chooses to expose; can be tuned
  per project.

Critically, visibility level is **per-engagement on a project**, not
per-party globally. The same party can be operator on one project and
referrer-blind on another.

### Markup vs commission

These look similar but are different in the schema and reporting:

- **Markup** — the operator buys work from a subcontractor at one price
  and bills it onward at a higher price. Bowden Works marks up Adi's
  hours when invoicing PlusROI.
- **Commission** — the referrer is paid a percentage of gross by the
  operator, without ever paying for the work themselves.

A line item is either a *cost being marked up* or a *cost being shared
out as commission*, not both, and the data model should keep them apart.

### Hierarchy: Client → Project → Set → Task

This is the work hierarchy. All four levels are structural.

- **Client** is the end party the work is for.
- **Project** is an engagement for a client, owned by an operator
  agency.
- **Set** is a distinct part of a project with a budget and a bundle
  of related tasks. Three common patterns:
  - **Single-set project** — a one-time piece of work; one set.
  - **Recurring sets** — a new set per billing period (monthly
    engagement → one set per month).
  - **Finite sets** — a multi-step project with a known sequence
    of sets.
- **Task** is a unit of work inside a set. Assigned to a person;
  tracked via time entries (hourly) and/or carrying a unit value or
  fixed price (per-unit / fixed-price comp).

"Phase" is **not** in this hierarchy. It's a colloquial label someone
might give a particular set — typically when the set represents a
build-phase like "Design Phase" or "Build Phase". The structural unit
is Set; Phase is one of several common naming patterns for sets.

(We considered renaming Set → Phase early on and rejected it: Phase
fits the build-phase pattern but would be wrong as the name for
monthly recurring sets.)

### Other terms to flag

- **Agency** vs **Client** — these are *roles a party plays in a
  context*, not properties of the party itself. AISV is a client on
  some projects and a referrer on others. The party is just "AISV";
  the role lives on the engagement.

- **Team member** — useful as a UI label inside a single org context
  ("Adi is a team member of Tingang"), but at the data layer the same
  concept is "an engagement of type freelancer/subcontractor".

- **Partner** — overloaded. Could mean profit-share collaborator
  (Rian↔Rob), official documented co-owner (Nicole Bowden), or
  long-term referrer. Avoid the bare word; specify
  **profit-share-partner**, **official-partner**, or **referral-partner**.