# Ubiquitous language — orchard — 2026-09-09 Read: all 9 files — `orchard/{billing,crm,support,scheduling,notifications}/`, both migrations, `README.md` | Skipped: nothing; no vendored, generated or superseded code is present, and both migrations create live tables. 19 terms (none left off the 40 cap), 2 synonym sets, 2 homonyms, 4 spoken but undeclared. Headline: three names for one person are joined by nothing but three docstrings and a shared integer — `clients.client_id` is `BIGINT PRIMARY KEY` with no foreign key to `customers`, and no module imports any other. ## Glossary | term | means | declared at | reach | |---|---|---|---| | Customer | someone who pays us; the id every other module keys off | `orchard/billing/models.py:6`, `migrations/001_customers.sql:1-2` | 3 endpoints, 1 table, 13 refs; defined-against by crm and support | | Client | the person we sell to — the same person as Customer | `orchard/crm/models.py:5`, `migrations/002_clients.sql:1-2` | 1 table, 6 refs, local to crm | | Account | support's word for the same person | `orchard/support/models.py:5` | 4 refs, local to support, no table | | Order (billing) | a purchase — what was bought and what was charged | `orchard/billing/models.py:22` | 1 endpoint, 4 refs, no table | | Invoice | a charge raised against a customer; carries `issued_at` only — nothing declares the monthly cycle | `orchard/billing/models.py:14` | 1 endpoint, 5 refs, no table | | email | the only field all three person-types carry; `UNIQUE` in `customers`, not in `clients` | `migrations/001_customers.sql:3`, `migrations/002_clients.sql:3` | 7 refs, 4 modules, both tables | | Job | a unit of queued work | `orchard/scheduling/queue.py:5` | 5 refs, local to scheduling, no table | | order (scheduling) | position in the run queue, lower runs first | `orchard/scheduling/queue.py:8` | 3 refs, local to scheduling | | account_manager | the staff member who owns a client relationship | `migrations/002_clients.sql:4`, `orchard/crm/models.py:10` | 1 table, 2 refs, local to crm | | billing_country | the country a customer is billed in | `migrations/001_customers.sql:4`, `orchard/billing/models.py:10` | 1 table, 2 refs | | lines | **declared but undefined** — an untyped `list` on Order and on the POST body; no line-item type exists | `orchard/billing/models.py:26`, `orchard/billing/api.py:18` | 1 endpoint, 2 refs | | plan | **declared but undefined** — a bare `str` on Account, never set, read or enumerated | `orchard/support/models.py:9` | 1 ref | | ... | 7 more glossary rows, cut to fit this listing field | | | Excluded as pattern vocabulary, not domain vocabulary: `ClientRepository`, `AccountService`, `QueueHandler`, `NotificationService`, `EmailHandler`. ## One idea, several names ### The person who pays us - **Customer** — `orchard/billing/models.py:6`, `migrations/001_customers.sql:1` — 13 refs, crosses the HTTP boundary at three paths (`/customers/{customer_id}`, `/invoices`, `/orders`) and the database boundary - **Client** — `orchard/crm/models.py:5`, `migrations/002_clients.sql:1` — 6 refs, one table, local to crm; no endpoint, no importer - **Account** — `orchard/support/models.py:5` — 4 refs, local to support; no table, no endpoint Costs: 3 declarations, 23 code references, 2 tables, 2 primary-key columns and 3 public endpoint paths. The expensive one is the endpoint prefix `/customers/` — an external contract that cannot be renamed without a deprecation window. Second is the pair of primary keys: `customers.customer_id` is `BIGSERIAL`, `clients.client_id` is plain `BIGINT` with no `REFERENCES`, so the claim at `orchard/crm/models.py:6` that `client_id IS customer_id` is enforced by prose and by nothing else. `migrations/002_clients.sql` also drops the `UNIQUE` on `email` that `001` carries, so the two tables are free to disagree about the same person today. The docstring dates the split to "the 2024 CRM migration" and records that the tables were never merged — this collision is a migration that stopped halfway, not a naming preference. Evidence points to: **Customer**. It is the oldest at the boundary (migration `001` precedes `002`), it is the only one of the three the outside world sees, it generates the ids the other two borrow (`BIGSERIAL` against `BIGINT`), and both rivals define themselves by pointing at it — `client_id IS customer_id`, `account_id is the billing customer_id` — while it points at nobody. Settling it costs crm and support a rename each and leaves the public API untouched; settling it the other way costs an API version. One caveat belongs with that winner: the README's word is neither of the three (see Spoken but not declared), and if **subscriber** turns out to be the business's real word, this decision reopens with a fourth candidate. ### The money total on a billing document - **amount_cents** — `orchard/billing/models.py:17` — 1 ref, on Invoice - **total_cents** — `orchard/billing/models.py:27` — 1 ref, on Order Costs: nearly nothing — two fields, one file, no table and no endpoint exposes either. Worth listing only because both are new-ish and the next billing document declared will pick a third name. Evidence points to: nothing decisive — both are one line old and neither has crossed a boundary. Cheapest to settle now by fiat, whichever a person prefers. ## One name, several ideas ### Order - means **a purchase** — what was bought and what was charged — at `orchard/billing/models.py:22`, exposed as `POST /customers/{customer_id}/orders` at `orchard/billing/api.py:17` - means **a sequence position** in the run queue, lower first, at `orchard/scheduling/queue.py:8` Costs: the quiet kind. `place_order` and `sort_by_order` both read correctly and mean unrelated things, so a grep for `order` to audit purchases returns the queue field, and any search-and-replace across both modules is wrong in one of them. The cost is deferred rather than absent: nothing imports across modules today, so the two never meet in one file — the day scheduling gains a job triggered by billing, they do, and a `list[Order]` parameter will be ambiguous at the signature. A maintainer is already paying interest on this by hand, in the comment at `orchard/scheduling/queue.py:12` that exists only to say the two are unrelated. Needs: a second word for the **scheduling** one — `position`, `sequence` or `rank`. That side is one `int` on one dataclass used by one function, entirely inside one module, against billing's Order sitting on a public endpoint; and "order" as a purchase is the business's word, while "order" as a position is generic English that any of three synonyms replaces without loss. ### Account - means **the person who pays us** at `orchard/support/models.py:5` - means **the sales relationship** — the book of business a staff member owns — inside `account_manager` at `migrations/002_clients.sql:4` and `orchard/crm/models.py:10` Costs: small and mostly to readers. A grep for `account` returns a customer record in support and a staff name field in crm, and a developer in crm meeting `account_manager` reasonably expects an `Account` nearby — there is none, because crm calls that same person `Client`. It is a compound rather than a competing declaration, which is why it ranks below Order. Needs: nothing of its own yet — settle it second. If Account loses the synonym decision above, support's `Account` becomes `Customer` and this collision dissolves without a separate conversation. Only if Account somehow wins does the CRM field need a word of its own (`relationship_owner`, `sales_owner`). ## Spoken but not declared - **subscriber** — heard in `README.md:5` and `README.md:6`, in bold, as the platform's headline noun — no class, table, column or endpoint anywhere. Missing concept or retired word is exactly the question, and it changes the synonym decision above: nothing in the code declares a subscription — no term, renewal, period or recurrence — so either the README describes a business the code has not caught up with, or "subscriber" is prose for the thing already called Customer. A person answers this, not the repo. - **churn / the 30-day read window** — heard in `README.md:6` ("Churned subscribers keep read access for 30 days") — no status, state, flag, timestamp or duration is declared in any module or either table. Either an unimplemented rule or a behaviour enforced somewhere outside this repo; which one decides whether it is a bug or a boundary. - **ticket** — heard in `README.md:5` and in the method name `open_ticket` at `orchard/support/models.py:13`, which takes a `subject` and returns a bare `int` — no Ticket type, no `tickets` table, nowhere for the subject to be stored. Support can open one and the codebase cannot describe one. Missing concept. - **the monthly invoice** — heard in `README.md:5` ("gets an invoice each month") — `Invoice` declares `issued_at` and nothing else; no period, cycle, due date or schedule is declared, and the scheduling module knows only about generic Jobs. ## Not audited - Every method and function body in the repo is a `...` stub, so each meaning above rests on a declaration, a docstring or a column type — no behaviour was available to confirm any of it, and the three docstrings asserting a shared id space are the load-bearing evidence for the synonym set. - No tests, fixtures or seed data exist to cross-check the names against runtime. - `Invoice`, `Order`, `Job` and the undeclared Ticket have no schema in this repo; only `customers` and `clients` are created. Whether those tables live in another repo or do not exist yet was not determinable here, and it bounds how confident the reach counts are for billing's nouns. - Renaming was not performed and is not proposed as an action: the winner and its price are recorded above for a person to decide. Say the word and this gets saved to the repo as `GLOSSARY.md`.