Audience: Claude Code, when a task touches structure.

Scope of this file. How the parts fit together and where new legs attach. Not a schema mirror — the database is the source of truth for schema, and this file records what is not visible from reading the code: why the boundaries sit where they do.

Read SCOPE.md first, then APPLICATION.md. SCOPE.md governs the shared ground — what HappyShip is, the service legs, the source language, and where a commit goes. APPLICATION.md is the authority for the application: what it does, and what the current phase builds. This file says how that is achieved. Where it conflicts with either, they govern and this file is what changes.

0. Status

Written before implementation, and parts of it have been overtaken since. The schema gap was filled from what step 0 built (§4.3); the rest of §13 is still open. The markers are SCOPE.md, the terms. An [OPEN] here is not permission to decide — stop and ask.

1. Shape

Four layers, one deployable service.

No microservices. No message bus. One service, one database, one object store.

2. Stack

Why Python. The engine is numeric and rule-heavy, the XLSX libraries are strongest here, and pricing rules read close to plain sentences — which matters because the product owner reviews logic, not implementation.

Why server-rendered, and why Flask. Every screen is a document — tables, forms that submit, uploads and downloads, a dashboard looked at once and then purged — so a separate front end would be two codebases in two languages for the same screens, with an API contract neither half can change alone: roughly double the build, and more than double the cost of a change, because one new field moves a response shape, a type, a component and everything that read the old shape. Flask rather than FastAPI or Starlette, because both are async, which buys nothing over a synchronous driver in front of a CPU-bound engine and costs a boundary through every handler, and FastAPI's validation and generated OpenAPI describe JSON bodies that no longer exist here. What the choice rules out is a screen assembled in the browser from data an endpoint hands it, not every request that is not a page load. Every page is rendered on the server. One request today returns something other than a page: the company-name check on the internal entity page posts to /entities/name-check when the field is left, and is answered with a status code and no body — held or free — so the page learns one fact and renders nothing from data. This is the reversible direction: a screen that later needs to behave like an application can be built that way on its own, where React everywhere and then simplifying is a rewrite.

Vendors are named in §7 and are deliberately replaceable. Nothing above the vendor line depends on which vendor is chosen.

3. The rate engine

A pure function. Given a shipment and a rate card, it returns computed charges. No database access, no network calls, no framework imports. Reference data is passed in, never fetched.

This is the one hard architectural constraint in the system. It exists so the engine can be tested without infrastructure, and so its correctness can be established independently of everything built on top of it.

The template parser (§9) is under the same constraint, for the same reason, and a test asserts it for both: neither module imports a database driver, a network client or a framework. The parser reads a file and returns rows and findings, and nothing in it writes.

Explainability is not optional (APPLICATION.md, engineering rules). It is what makes the engine's output auditable rather than merely correct.

Selecting which rate card applies happens outside the engine. A single upload or invoice may span multiple rate cards. Resolution rules live in RULES-<leg>.md.

4. Data

4.1 Database vs object storage

Files never touch local disk. Uploads go to object storage on receipt. Hosted filesystems are ephemeral, and a file written to disk disappears on redeploy. This is one of two constraints that make the local-to-hosted move trivial (§6).

This is a rule about the code path, not about the machine. The application always writes through the object-storage API; where that API points is configuration (§6). Local development points at the object store's free tier — no cost, no emulator, and the same code path as production. It does not mean "no local development"; it means no ./uploads directory.

Results. A costing run produces one result record per shipment per scenario.

Dashboards sort, filter, and display the full result set, so result detail lives in Postgres, indexed for those queries. Object storage holds the generated file for download, not the queryable copy. Results land in Postgres during a run and the dashboard reads them from there; they do not survive delivery.

Because comparison data does not survive a run, the database is small and steady, and library rate cards are the largest permanent thing in it.

Purge triggers. The comparison upload is purged from object storage once parsing succeeds. Result detail is purged from Postgres once the report is delivered. Whether purge is configurable, and what it defaults to, is APPLICATION.md.

Library cards are exempt from purge — they are stored and persist by design (APPLICATION.md, rate cards).

4.2 Limits

Dataset ceilings and append behavior no longer apply in phase 1 — there is no dataset model, and each run is one upload.

A per-upload row limit is still unset. [OPEN]

4.3 Schema decisions from step 0

The database is the source of truth for the schema; the migrations under app/db/migrations/ carry the tables, keys and constraints, and the rule each implements is a comment beside it. This section records only what a reader could not recover from them: why the boundaries sit where they do.

Entity scoping and forced row-level security sit on every table, including the public ones. Regions, the reference-standard designations and the standard's own rows are readable by every entity, and they still carry an owning entity (HappyShip) and forced policies. The alternative, an unscoped table for public data, would be the one table a missing filter could not fail closed on, and the rule that every table carries an owner is worth more than the exception. Forcing binds the migration role too, so the owner cannot be the leak. Two consequences follow, for whoever writes the next migration: a data migration that touches rows must bind its transaction to the entity that owns them, since the migration role sees nothing otherwise; and creating or acting on an entity today is done by a session bound to that entity, until the internal tool's separate logged path exists.

A typed identifier's owner prefix is a CHECK, and the collision check depends on it. rate_cards constrains the first four characters of rate_id to entity_id. Forced row-level security means a session sees only its own entity's rows, while a unique constraint is enforced beneath those policies and sees every row — so a SELECT-based collision check inside a bound session can report clear against a row it cannot see, and the INSERT then fails on a constraint the check never consulted. The prefix CHECK removes that gap by confining every identifier that could collide to the owning entity, which is the session's own visibility. It is a precondition of the ID scheme (APPLICATION.md, the ID scheme), not a local nicety, and a table minting a new type letter without it inherits the gap.

A reference standard is a rate card held by HappyShip plus a designation naming it, not a table of its own. The owning entity on the row is custody and isolation — which entity the row belongs to, and therefore who may read it — never ownership of the rates, which are the carrier's. Its rows have exactly a card's shape, a client's card compares against it cell by cell, and the parser validates a filled template against its structure, so a parallel table would be the same shape twice. The cross-entity read this needs is an explicit, tested policy on the card and row tables, opened only for a designated card, read-only, and beside the two surfaces §5 names. It is not an exception to isolation: an undesignated card HappyShip holds is as private as anyone's, and a test asserts both directions.

A login's key is its email address, and a publication event snapshots that address rather than holding a foreign key to it. The address is the account (APPLICATION.md, identity and access), so nothing else identifies a login. Login deletion is a hard delete and a deleted address may be logged again, while the publication record must keep "this login, at this time." A foreign key would either block the delete or lose the record; the snapshot does neither.

Charge rows carry a sequence; per-zone charge rows do not. Structure is which charges exist, in what order (RULES-LAST-MILE.md), so the order is part of a standard's identity and must be stored, and one charge code recurs across dated rows and brackets, so the row itself does not carry its position. The four per-zone rows are one row per code in an order the doc fixes, so the code alone places them.

[UNBUILT] The fuel rate is scoped by service family — Ground and Home Delivery share one percentage while express is jet-fuel-based — so the table carries that column before a second carrier arrives rather than after. Every row of the fuel series carries its effective date from the first migration, since every read of the series is by governing date and a row without one cannot be placed in it.

The 24 charge codes are a check constraint rather than a table, deliberately. The set is code on purpose (APPLICATION.md, master data and the reference standard): an open catalog is a door to uncontrolled codes, and a constraint a deploy is the only way to widen is what stops the set drifting. A second carrier does not weaken this — it arrives as its own coded set rather than as rows someone types into a catalog, so the constraint is not the thing a second carrier forces open.

[UNBUILT] The rule report will read these same constants (APPLICATION.md, internal reference views) — generated from them rather than describing them, so the constraint, the engine and the page a staff member reads cannot disagree. It arrives at step 5.

Migrations must apply, in order, to an empty database. The test fixture drops and recreates the schema and applies every migration, then seeds, rather than truncating and re-seeding: a truncate cannot restore rows that a NOT NULL data migration populated, since the seed that re-inserts them predates the column. The first data migration failed on a fresh apply and had been masked on the dev database, where the seed had already run before the migration existed; the shape will recur whenever a migration depends on seeded data, and the fresh apply is the only check that catches it.

5. Isolation

APPLICATION.md requires isolation at the data layer so a missing filter fails closed. Four mechanisms, in order of what they buy:

1. Every table carries an owning entity, from the first migration. This is the single most expensive thing to retrofit — it touches every table and every query.
2. Postgres row-level security. Policies live on the table, not in application queries. A query missing its filter returns nothing rather than everything.
3. Entity comes from the session, never from the request. Not a URL parameter, not a body field. Set once at authentication; every query inherits it.
4. Adversarial tests, at the data layer and the view layer. A view cannot skip scoping by being written: the lifecycle that binds an entity runs before every request, so there is no per-view opt-in to forget, and a test asserts every rule in the url_map is served under it. What the tests must assert is APPLICATION.md. Nothing runs them automatically. The repo has one workflow and it runs no tests — it regenerates the handbook (SCOPE.md). So the suite gates whoever runs it and nobody else, and a commit reaches main with no test gate, including the bot's. A workflow that runs the suite on every push is wanted rather than built. [OPEN]

Two surfaces reach across entities, and no others. The mechanisms beneath them are listed rather than counted, because the count has been wrong twice — once when the login and session lookups arrived, once when the roster did — and a list gains an entry where a number needs correcting. The list carries no count for the same reason, that being the third time:

• The reference-standard policy. A card designated as a reference standard, and its rows, are readable by any session bound to an existing entity, because reference standards are public (APPLICATION.md, visibility classes) — explicit, read-only and tested in both directions (§4.3).
• The login and session lookups (§10), which no binding could answer, because resolving them is what produces one.
• The roster functions, which return the entity list and create and delete entities (APPLICATION.md, the internal surface).
• The entity-record functions, which read and write one entity's record at a time — its fields, counters, ship-from locations and card metadata, never contents (APPLICATION.md, the internal surface).
• The login-address functions, which read every address across every entity, and create and delete them.
• The content path, below, which is the only one that logs. [UNBUILT]
• The card-entry function, which writes a card and its rows into another entity's library on HappyShip's behalf (APPLICATION.md, who writes a card). It is the only one that writes card contents; the roster, entity-record and login-address functions above it write too. [UNBUILT] It does not log.

What bounds an exemption is the shape of what it returns, never a predicate. A predicate bounds which rows and says nothing about which columns, so a role-scoped policy with USING (true) on a table yields every column of every row — the internal-only ones included — and nothing stops a caller selecting one nobody intended. That is a convention, not a ceiling. Every cross-entity exemption is therefore bounded by its return shape — a definer function's return type, a view's columns, or column grants — so that widening it takes a migration somebody can see. The two lookups above are an instance of this rule rather than an exception to it: each takes one value and returns one entityID, and the signature is the ceiling.

A write exemption is bounded by what it may write, since a return type bounds nothing when the point of the call is its effect. app_card_create_for returns one identifier and writes a card and its rows into another entity's library, so the return type is no ceiling at all. What bounds it instead is the set of tables it touches, its parameter list (there is no parameter for an entity other than the target, nor for a rateID), the values it fixes rather than accepts — a card it writes is always a draft and never published — and the grant that lets it run, held by one role the internal surface alone uses. Widening any of the four takes a migration somebody can see, which is what the rule above is for. [UNBUILT] It does not yet log, and the audit write described below is where that belongs: no cross-entity write logs today, and a write into another entity's library is the one that most obviously should.

The internal management tool (APPLICATION.md) goes through a separate, logged path — never a flag on the normal path.

[UNBUILT] The audit write happens inside the function that returns the contents, in one transaction. Reading another entity's private card contents without logging is not possible because they are one operation, and a failed audit write fails the read. That is structural rather than procedural: nobody has to remember a log line, because the only path to those contents runs through the thing that records it — a designated reference standard is public and readable without a log, which is what the audit is not for. That function meets the bounding rule in the ordinary way — its return type is the ceiling — and the write path is the same shape, the audit row landing in the transaction that creates the card.

[UNBUILT] The application role will hold INSERT and not SELECT on the audit table. It writes and can never read back, which is what makes the table an audit rather than a log the audited surface can read: an internal session can be made to write a row and cannot be made to show one. It inverts the lookup role — that one exists so the application can read what it otherwise could not, this one so it can write what it cannot. Reading the audit is out of band, by whoever holds the migrate credential. Every table carries an owning entity, and here that is the acting entity, HappyShip, because the action is HappyShip's; the target entity is a separate column doing a separate job, and merging the two would file the row under the entity it was written about.

The run-time pool (APPLICATION.md) is the second. It is not an exception to the isolation rules there: it reads only cards whose publication flag is set, and it returns computed results, never card contents. The flag is what the pool tests, never the owner's act. The pool distinguishes none of the ways the flag came to be set or cleared, so a card withdrawn because its entity lost authorization is as invisible as one the owner withdrew. The adversarial isolation tests required by APPLICATION.md extend to it.

Identity is not authentication. Entity scoping exists from step 0 and sessions from step 1; sign-in exists from step 2 (§8). Step 0 runs against a seeded entity with nobody logging into it, and step 1 runs against a real session that nobody has signed in to.

6. Portability

Two constraints make the hosting choice reversible. Both cost nothing now and are expensive to undo:

• All configuration through environment variables. No connection strings, paths, or keys in code.
• All files in object storage. Never the local filesystem.

Additionally: run the same Postgres major version locally as in hosted environments, and confirm any extension exists on the target before depending on it.

The move from local to hosted is a few hours' work — provision, dump and restore, repoint environment variables, deploy. The difficulty is never the move; it is data you cannot afford to lose. Move before there is data worth protecting (§8).

7. Hosting

Selection rule: every vendor must have a usable free tier and a reasonable paid tier on the same platform. Start free, upgrade in place, never migrate. A vendor that is cheapest at zero but forces a move at scale is disqualified — the migration costs more than the savings.

Each row is one platform from free through production. Upgrading is a plan change, not a move.

Auth is not a vendor and has no row: passwordless sign-in, sessions and entity binding are application code against Postgres (§10), so there is nothing to select, no free tier to outgrow and no user-count threshold to watch, and what auth stores is covered by the Postgres row above.

The application needs no static host of its own, and that is deliberate. It renders its own HTML and serves its own assets from the one service of §1, so nothing of the application's is deployed apart from it and there is no second thing to point a domain at. Two static surfaces do exist beside it and neither is the application's, which is why neither takes a row above: the public website, SCOPE.md's to name and WEBSITE.md's to describe, and the handbook (SCOPE.md). Both sit on Cloudflare, already a named vendor here, so neither adds a platform to select or outgrow.

Prices and tier limits change; verify before committing.

Free-tier compute sleeps when idle. Cold starts are acceptable while testing on internal data and not acceptable once an external user might arrive, so compute is the first upgrade — at the §8 gate.

Point-in-time restore is the one thing not to economize on. Free-tier Postgres generally lacks it. Acceptable for data that can be regenerated; not acceptable once real client rate cards are stored.

Do not introduce Kubernetes, microservices, additional datastores, or a message broker.

Even with upgrade-in-place, §6's portability constraints hold. They are what makes the selection rule a convenience rather than a dependency.

8. Build sequence

All steps deliver phase 1 as defined in APPLICATION.md.

Step 0 is not finished, and later steps have run ahead of it. What exists is the schema, the reference-data seed and the parser, plus rate-for-rate comparison — which compares two cards and is not what §1 and §3 define the rate engine as. Step 0 owes two things:

• [UNBUILT] The costing engine. Given a shipment and a rate card, compute charges with an explanation per line (§1, §3). Nothing in app/engine/ accepts a shipment.
• [UNBUILT] Accessorial behavior. The 24 charge codes carry prices and nothing else. No trigger test, no minimum billable weight, no highest-wins evaluation and no fuel evaluator exists, so a code can be priced and cannot be applied.

The invoice verification in step 0's row waits on both, and stays where it is. Nothing is rescheduled and the gate does not move: it is step 0's obligation because the reason below has not changed.

The internal portal moved ahead of everything but the schema. Nothing can be seeded without its screens and nothing can be compared without seeded data. Step 0 still runs against a seeded entity with nobody logging into it (§5); step 1 no longer does, for the reason below.

The session moved into step 1 with the screens, because the two were waiting on each other — sign-in authenticates against pre-registered addresses, nothing can be registered until the logins screen exists, and that screen needs a session to know which entity is acting. What identifies the acting entity is what the row-level security policies read (§5), so a stand-in for it is not cosmetic: it reaches every query written in step 1 and every test around them. Building the seeding screens against a real session and real entity binding from the first line costs less than threading a placeholder through them and pulling it back out in step 2.

The dev-only route that mints a session is temporary work toward admitted work, not scaffolding. What APPLICATION.md's not-built rule forbids stubbing and scaffolding for is work phase 1 does not admit, and auth and login are admitted — so the rule does not reach this, and step 2 carries the obligation that makes it temporary rather than permanent: the route is deleted when sign-in lands.

The route sits inside the entity-binding rule rather than being an exception to it, which is what lets it exist inside the security boundary at all: it supplies an address, finds the login record and mints a session the ordinary way, skipping the code and nothing else, so the entity is still read from the login record and never from the request (§10). It cannot run before a login exists, so the first internal login is seeded alongside the HappyShip entity — the same seed, one row wider.

The first cut is the seeding screens only — create an entity · log an email address against an entity · upload a carrier-published card and name it a reference standard · enter a card on an entity's behalf · the values the card fields read (carrier list, entity list, currency, weight unit, ships-from regions) — not one tier and not all master data, so what step 1 owes each is that it is present, not that it has a page (APPLICATION.md, master data and the reference standard) · authorization to publish. Out of it: coupons, payments, activity metadata and the rule report, all of which stay at step 5. The HappyShip entity is a seed rather than something created through the portal, because internal logins bind to it.

The handbook is not in this sequence at all, and did not move within it. It needs no application running (SCOPE.md), so no step waits on it and it waits on none. It was listed at step 5 while it was a screen of the internal tool, and stopped being one.

Auth moved ahead of self-serve card upload, and not ahead of the whole library. Self-serve upload is an authenticated act by a card's owner (APPLICATION.md), so auth and entity binding cannot sit after it — and that reason reaches upload alone. The rest of step 3's library work depends on a session rather than on sign-in, which the dev-only route supplies, so it ran before step 2 instead of after it: the library dashboard, one card's detail, the lifecycle transitions and the publication act with its consent record are built while auth is not. Email delivery arrives with auth, which is where email infrastructure first exists.

Authorization arrives before the billing it exists to serve, and that is deliberate. It is a setting from step 1, while what makes granting it a paid decision waits for Stripe at step 6. Step 1 asks only whether the flag may be set, never why — which is what lets the pool run locally, before there is anything to charge for entering it.

Report generation lands with the comparison steps, at step 3.

The gate

Steps 0–4 run entirely on the product owner's own data, on the local machine, at no hosting cost. "Local" here means no deployed compute and no paid tier — files still go to the object store's free tier per §4.1, never to local disk.

Before step 5 and before any external user, three checks:

1. Is the engine right? Real invoices, line by line, matching. If this fails, nothing downstream matters.
2. Is the template usable by someone else? The owner will fill it correctly because he knows what every column means. That is exactly what an outside user will not do.
3. Does the output say something the reader did not know?

Expect ingest rejection handling to get its first real test after the gate, not before — internally produced files are unrepresentatively clean.

Step 0 is the load-bearing step

Its cost is not code volume; it is writing down the calculation rules precisely and verifying output against known-correct invoices. If those rules are ready when step 0 begins, the step holds its estimate. If they are discovered through wrong invoice totals, it does not.

9. Ingest

Single sheet. HappyShip supplies the template. Which formats it comes in, and what happens to a file that does not conform, are APPLICATION.md. An XLSX with more than one populated sheet is rejected, so the two formats stay interchangeable and the parser has one shape to handle.

The template is generated from a reference standard, with structure locked to it (RULES-LAST-MILE.md). The parser knows the expected structure before opening the file, so conformance is a comparison against that structure rather than an inference from what the file contains.

Input is split between the uploaded file and a web form. Which fields go where is decided by the product owner, not derived. The split is recorded in RULES-<leg>.md, and those two are the whole input surface.

The file is a grid for humans; the database is one row per zone, weight, and service. The parser transposes. Nothing downstream sees the grid.

Template column definitions live in RULES-<leg>.md.

10. Auth

Passwordless — a verification code emailed to a pre-registered address (APPLICATION.md, identity and access). No stored passwords, no reset flow, nothing to breach.

The code is six digits. The sign-in screen takes it in six separate fields, one per digit, grouped in one fieldset (home.md, sign-in). Six was decided at the build — the sign-in shell landed with it at 53a57ff — and is written here after the fact: on this point the code led the document, not the other way round. Nothing generates, sends, stores or checks a code yet. [UNBUILT] The sign-in pages are a shell with no code lifecycle, and /dev/session is the only way a session is minted today.

Whether a code is single use is not stated anywhere. [OPEN] home.md names single use among the mechanics this section owns without deciding it, and no code path exists that could make it true or false.

Three more of the code's mechanics are undecided, and none is stated in this file or in home.md:

• How long a code stays valid. [OPEN]
• How soon a code may be resent, and how many times. [OPEN]
• What a wrong code does — whether it costs an attempt, how many attempts one code allows, and whether the screen says how many remain. [OPEN]

Entity binding. The entity is bound at session establishment, read from the login record — never from the request (§5).

Session length. Two limits, and the session ends at whichever arrives first. An absolute lifetime of 7 days from establishment, which no amount of activity extends. And an idle timeout of 24 hours, which every request resets, capped by the absolute — an active user is signed out at 7 days, not sooner.

The cookie is persistent, not a session cookie, so closing the browser does not end the session.

Sign-out ends a session, and it is the only way a user ends their own (APPLICATION.md, identity and access).

Why the limits are this long. Re-authentication here is an email round trip, so every expiry is one more chance for a delivery failure to sit between a client and their own work — and email is infrastructure rather than a convenience, not a property this design can shorten its way out of (§10.1). What a short session would otherwise protect against is a session outliving the right to it, and that is already handled by a stronger mechanism than a timer: deleting a login ends its session immediately, checked per request rather than at expiry (APPLICATION.md, identity and access). Shortening these limits therefore buys little, and is paid for in email round trips.

The login code email is always EN (APPLICATION.md). The code-sending path has no locale to resolve against (§11).

Consequence: email becomes infrastructure rather than a convenience. Every login depends on delivery, which is stricter than password auth where email only matters at reset. It is stricter still now that email carries more than the login code — the welcome email, the delete notification and the owner notification depend on delivery too (§10.1).

10.1 Email is infrastructure rather than a convenience

Email is no longer only the login path. It is infrastructure, not a convenience, and four things depend on delivery: the login code, the welcome email when an address is logged, the notification when a login is deleted, and the notification to an owner when HappyShip has entered a card on that entity's behalf (APPLICATION.md). The report of a completed run is not among them.

11. Building for translation

The language policy is APPLICATION.md, language in the application — which locales, per-login selection, how a user-facing string is written while the i18n layer does not exist, and the login code email always EN. This section is only what that policy costs architecturally.

CN is in from step 1, not added at the end. Layout breaks appear per screen; retrofitting means re-reviewing every screen.

The step 1 portal follows the login, since a step-1 session carries a login record and a login record carries a language preference; the browser rule governs only before a session exists, which in step 1 means before the dev route runs (APPLICATION.md, language in the application).

Length is the constraint, and buttons are where it bites. Buttons are fixed-position elements in a row, so one long label displaces its neighbors. Paragraphs reflow and tables wrap — neither is a structural problem.

Detailed styling rules belong in brand/STYLE.md.

12. Known future work

Recorded so it is not rediscovered as a surprise. None of this is phase 1. This section holds the architectural consequences of work not yet admitted, not deferred decisions — those are BACKLOG.md.

Cross-carrier zone normalization. A FedEx zone 5 is not a UPS zone 5. Rate-to-rate comparison across carriers needs a common basis — a normalization problem one level above the grid. Does not bite while phase 1 is FedEx-only.

Legs beyond last mile. Warehouse, drayage, and global mile attach at the rate table: the charge model is shared, the table shape is leg-specific.

Higher upload volumes. Present limits are set well below what the design supports. Raising them affects worker memory and result handling, not structure.

13. Gaps

Where an open decision lives is SCOPE.md, the terms. This table holds the architectural consequence of one, never the decision itself.

14. Running the suite

The test database is named in app/README.md, supplied by nothing and checked by nothing. The suite reads two variables, and app/tests/conftest.py stops the run when either is unset:

There are two roles because the suite tests grants. The migration role builds the schema and binds test data; a grant is tested by connecting as the role it is granted to, and that role is happyship_app. One connection could build the schema or test the grant, never both.

No committed file sets either variable — no dotenv, no shell profile, no default in the fixture — so every run supplies both inline. From app/:

``bash HAPPYSHIP_TEST_DATABASE_URL=postgresql://happyship_migrate@localhost/happyship_test HAPPYSHIP_TEST_APP_DATABASE_URL=postgresql://happyship_app@localhost/happyship_test ../.venv/bin/python -m pytest -q -rfE -p no:cacheprovider ``

The rate card specimen needs no variable: it defaults to the committed fixture.

The fixture drops schema public. It rebuilds from nothing (§4.3): DROP SCHEMA public CASCADE, every migration, then the seed. Nothing in it looks at which database it was given. Pointed at happyship, it destroys dev — the owner's walk entities, and every applied migration with the hash it was verified against — and dev is never rebuilt.

The guard is a precondition on every run, not a step in it. A run does not start unless both hold:

1. Both strings end in /happyship_test. Either one ending anywhere else, and the run does not start.
2. No other run is active. On macOS the interpreter lists as Python -m pytest, capital P, so a case-sensitive match misses it: pgrep -if "python -m pytest" finds a run, and pkill -if "python -m pytest" ends one. There is no timeout command on this machine.

The absence is the defect. A destructive command whose only safeguard is the operator typing carefully is not safeguarded. The warning in app/README.md is that same safeguard, written down.

• Whether the two variables get a committed configuration. [OPEN]
• Whether the guard moves into the harness, out of the operator's hands. [OPEN]

Process lives in tiers, by ownership:

• CLAUDE.md — universal working rules, every project. Part A (behavioral), Part B (code discipline), Part C (universal how-tos).
• SCOPE.md — the project's index: what it is, its terms, which document to open, where a commit goes. It declares every other file the project has.
• XYZ.md — project-specific files, in the repo, each declared in SCOPE.md.

Precedence. SCOPE.md governs project-specific matters. Where the two genuinely conflict, stop and ask.

Part A — Behavioral (applies to all work)

Read the governance files first. SCOPE.md at the start of every task — in Code, from origin/main; in a chat, the project-folder copy, treating its line-1 stamp as a claim. CLAUDE.md Parts B and C when the task touches the repo or governance. Then only the docs the task touches, from the set SCOPE.md lists. Read once per chat at the first task; after a prompt lands, check line 1 of each governance file and re-read only those whose version changed.

Governance files are not permanent. When a discussion produces a claim that conflicts with one, amending is a decision that waits for my go: the rule and its reason go into the doc that owns them. Raise it, agree it, amend the file — then build. Never build to a decision a document still contradicts.

If a required governance file is missing, stop and ask. If SCOPE.md itself is missing, ask whether it was not uploaded or this is a new project (Part C).

Discussion mode by default — wait for the go. No prompts, code, or files until I say so. Surfacing options and recommending one is always fine. Do not draft until all your own questions are answered.

Be concise and direct. Push back when you disagree. Do not explain your reasoning unless asked.

Match the mode. Not every chat is about code; if unsure, ask.

Don't guess. If something is missing, ambiguous, or uncertain, stop and ask. When you agree with a proposal of mine, restate it more concisely without drifting toward your own phrasing; if you still see a problem, say so.

Flag once, then comply. A conflict with a governance file or an earlier decision is said once in the chat, then the work proceeds as asked and the amendment lands in the same batch. Once I have given a reason and said settled, the point is logged with its reason and is not raised again.

Don't add what wasn't asked for. No inventing, extrapolating, or writing conclusions into a governance file without my go. Do not invent local folders — ask where temporary files go.

State a limitation only where it qualifies the answer, never as a standing disclaimer.

Write US English, unless SCOPE.md sets otherwise. Identifiers, file paths, CSS custom properties, quoted third-party text, and files synced in from another repo keep the spelling they have.

The repo is the source of truth. Git main is authoritative — not another conversation, not memory, not an attached or synced copy. On conflict, flag, stop, and ask.

Show a draft in its own format. A governance doc as a markdown file, a page as HTML, a deck as slides. A prompt for Code stays in a code block.

Prompts are for Claude Code. Clear, scoped, based on what we discussed, always in a code block. An amended prompt is regenerated in full.

One prompt at a time. Give me the first, wait for the result, then the next.

Handoffs are for a new chat. Suggest one when a conversation drifts, runs long, or a session closes. Written in a code block.

Part B — Code discipline (projects with a git repo)

Clauses referencing origin/main, pushing, or PRs apply only where the repo has a remote; the rest apply to local-only repos too.

Read governance docs from origin/main. git fetch origin first, then git show origin/main:<file> — never the working tree, never the project folder. The folder copy's line-1 stamp may be read for the sync audit.

Sync audit. At the start of every repo-touching task, compare line 1 of every governance file SCOPE.md lists (plus CLAUDE.md, SCOPE.md, and any stamped non-.md governance file) between origin/main and the project folder. Code reads git; the chat reads the folder; each supplies its half. Where they differ, the higher version is current — flag it and sync to it.

Verify the git identity before pushing. gh auth status at the start of any task that will push; confirm it matches the account in SCOPE.md. Never run gh auth switch or gh auth login — on a mismatch, stop and give me the command.

Governance docs go direct to main, pushed immediately. No branch, no PR. Exception: a governance file SCOPE.md declares publicly served keeps branch and PR for an authored change. A generated file is never branch-and-PR; its generator and sources are. Sources first, then the regenerated file in its own commit on top. Never one commit, never an amend.

Governance docs carry a version stamp. Line 1 is exactly v### | yyyy-mm-dd | #### lines — nothing above it. A file whose format forbids bare text at the top carries the same stamp on the first line of its opening comment. Bump v### once per commit, not per revision. Date and line count come from the machine (date +%F, wc -l), local timezone, never typed.

Correcting a claim means correcting what justified it. After an edit to a governance doc, run the reason check (it prints every because, since, which is why, so that, the reason, this means sentence in the touched sections) and put its output in the recap. Each hit that no longer follows is fixed in the same commit.

Protect main when it deploys from main. Branch and PR for anything on a deploying surface that nothing validates; direct to main for anything the build validates before publishing, plus governance docs. The test: does a bad commit reach readers with nothing catching it? If unclear, ask. Where the project does not deploy from main, commit direct and branch only for isolation.

PR flow: one feature branch per task from an up-to-date main → commit locally → push the branch. When I say PR, Code opens it, merges it, and cleans up (git checkout main, git pull origin main, git branch -d <branch>, git remote prune origin) in one run, no stop between. I look at the result on main. Name it type/short-description; type is one of feat, fix, docs, refactor, chore, style, test, perf, build, ci, uat.

Style changes get their own commit. When a UI/UX decision applies project-wide, ask whether STYLE.md and/or the token file should change. Any change to either is its own commit.

A bug found in a task is fixed and tested in that task. It becomes a tracker row only when it is outside the task's scope and I say so.

Show client-facing changes on localhost before commit, with caching disabled or a cache-busted URL. Every URL handed to me — localhost or live — is a full link I can copy-paste, requested by Code first and confirmed to answer 200, and it goes in the recap. A live URL is checked after the deploy confirms, never before.

A run that commits, bumps a stamp, or raises a finding ends with a recap (Part C).

Part C — Universal how-tos

how-to: keep CLAUDE.md in sync

The master copy lives on local disk at /Users/swai/sw805206/CLAUDE.md. Every project repo holds a copy and reconciles against the master.

Publishing a change (project A). Edit the copy in project A's repo, commit to main, copy the file back to the disk master. Not finished until both.

Reconciling a copy (any project). At the start of a task, compare line 1 of the repo copy against the disk master; sync to the later version automatically and report it. Disk master later: copy in, commit, push. Repo copy later: copy out.

Human steps after any change. Re-paste Part A into Claude's global settings; upload the current file to each Claude project folder.

how-to: start a new project

1. Bootstrap. I create a Claude project folder, upload CLAUDE.md, and describe the project. Finding no SCOPE.md, the chat asks whether one is coming or whether this chat authors it.
2. Author SCOPE.md. Discuss, then write v001 beside CLAUDE.md. It declares the project type, the files it requires, whether it deploys from main, and its branch/PR discipline.
3. The repo, where the project is git-related. Path recorded in SCOPE.md. Before the first commit, git config user.email in the fresh clone must match the account the project owns. Use the clone URL form belonging to that account.
4. Scaffold every file SCOPE.md names, at v001, direct to main with SCOPE.md — except a file declared publicly served, which takes branch and PR from creation. Copy CLAUDE.md from the disk master, byte-identical. Ignore local tooling directories at creation.

SCOPE.md v001 is hand-stamped; the first Code commit corrects it.

how-to: write a handoff

A handoff transfers what a chat knows to a new chat in the same project. It is never written to a file. The old chat stays open until the new one has picked up the work; anything needed beyond that window belongs in the repo.

It must carry:

1. What was done, and what is open, in enough detail to act on.
2. Provenance on every claim — verified against the repo this session, or inherited from the last handoff.
3. The repo, precisely — HEAD commit, tree state, suite numbers, open PRs, anything waiting on me.
4. Which .md files are stale, and the version each should be.
5. Every open tracker row touched this session, by ID.
6. Next steps in order, marking which is a discussion and which is a prompt.
7. What was dropped, and why.
8. Environment landmines no governing doc records.

how-to: write a recap

Code's last output of a run that committed, bumped a stamp, or raised a finding. A code block, for paste-back to chat.

1. Outcome — executed, or stopped and why (misalignment, error, bug), and what is needed from me.
2. Done — what changed, with commit SHAs.
3. Tested — what and how; a user action counts only if the test performed it. The URL to look at, localhost or live, confirmed answering.
4. Found — findings and misalignments, each with its tracker ID.
5. Stamps — every file bumped, with its new version. This is the chat's half of the next sync audit.
6. Suggested next, if any.

Audience: Claude Code and Claude chats, at the start of every task.

What this file holds. What HappyShip is, the terms, which document to open, where a commit goes, what the handbook renders. The index: a file not declared here does not exist.

0. Rules for using this document

1. Open the one document for the surface you are working on (§5) and follow it onward.
2. The terms are §0.1, the one place they are defined.
3. A rule written for the website or the application does not carry to the other unless it says so.
4. A reference that crosses a file names the file and the topic, never a section number. A restructure searches the other files for the old names before it lands.

0.1 The terms

Markers, in any markdown document:

Square brackets mark these two and nothing else. Anything not done is a TRACKER.md row, never a note in the prose. Built things carry nothing; the repository is the evidence.

The tracker row: | T-### | Module | Role | Phase | Status | Item | Evidence |. Module names the module the row belongs to, or is blank for work belonging to none. Role is internal, external or both, or is blank where the row has no user-facing side. Phase names the phase in §3.3, or is blank for work belonging to none.

Features are numbered by module — C### common, E### entity, H### home — and live in test.md; a check is the feature's ID with a trailing letter (E006a). TRACKER.md keeps every other module's rows until each moves the same way.

✅ passed · ❌ contradicts the file, or the file asks for it and the code has nothing · ✏️ built, not the way the file says · blank, not walked against the current build.

A both row has one status, the lower of its two sides — unbuilt until both sides are built, built until both are verified. Its done evidence names both sides, or one test that exercises both.

A row walks open → unbuilt → built → done. A revision sends it back to open or unbuilt on the same row, with one line appended saying why.

IDs are assigned when the row is raised, in sequence, never reused.

1. What HappyShip is

HappyShip provides logistics rate analytics and advisory. The analytical services are rate comparison, rate management, invoice audit and shipment tracking; the advisory services include rate negotiation and rate sourcing. It is a control tower: it holds the analytical picture, it does not hold the commercial relationship, and it does not profit from rate arbitrage.

Sells: rate and invoice analytics; consultation on rate optimization and carrier negotiation. Both charged to clients.

Does not do: direct contract negotiation · rate legitimization · dispute execution · payment processing between entities · adding margin to any rate.

2. Project scope

Two surfaces: the HappyShip website, and the HappyShip application (SaaS). The product definition will keep evolving; the website carries the public statement as it stands, and is not where the plan is published.

3. Product description

3.1 Services

For says what an entity is doing, never what it is. There is no stored role. This table is the full set of functions, not the built set.

3.2 Service legs

Rates are organized by leg. Each leg has its own rate table shape and its own RULES-<leg>.md. Carriers vary within a leg; a new carrier is a section in that leg's rules, never a new file.

Near term is legs 1 and 2 only. Legs 3–5 have no phase and no RULES- file until one is assigned.

3.3 Phases

A phase is a decision, not a document. It is defined by the product owner, one at a time, and is not always tied to a leg. The next phase is written here when it is chosen; its work is TRACKER.md rows carrying the phase, and the two must agree.

Phase 1a:

1. All foundational builds
2. Last mile — Compare rates (rate-for-rate), Manage rates
3. Carrier and carrier services — FedEx Ground & Home Delivery

Phase 1b: shipment-cost comparison — the shipment profile template, the zip-to-zone list, and the shipment upload and outputs.

Out of scope — Audit invoices, Track shipments. Design is not started. [OPEN] T-075

4. Language

Language, dates and times, and identifiers are common.md's.

5. Documents

Shared by both surfaces.

The website.

The application. Durable files describe the whole application, every phase and leg, and are not rewritten when a phase advances.

Subject files are working files. One per module, spec-heavy before the build. Its rules move to the durable file that owns them; its tests are in the suite; its open items are TRACKER.md rows. When the module is built and tested and its rows are done, the file is committed and the module is closed. A new issue reopens it as a draft in chat.

The header states the default: everything is [UNBUILT] unless marked. Each section heading names its row (## 2.3 Contract — T-0##); a paragraph carries a marker only where it differs from its section.

Retired, kept as record. BACKLOG.md and DECISIONS.md are no longer written. Their BL-### and DEC-### IDs stay valid where cited.

The handbook renders SCOPE.md, CLAUDE.md, ARCHITECTURE.md, STYLE.md, DICTIONARY.md, WEBSITE.md, common.md, entity.md, home.md and test.md; every other file in this list stays in the repository unrendered until it is rebuilt.

6. Repository

6.1 Where it lives

Subject files are live files. TRACKER.md and DATA.md are not: they are governance docs like any other — master in the repo, direct to main, in the sync audit, rendered in the handbook. A chat reads them from the handbook.

1. Drafted in chat, for discussion.
2. When ready for Code, the chat writes the prompt and asks for the file to be saved to HStemp.
3. Code reads it there, builds, and reports the outcome and the URL to test. Code never edits a file in HStemp. At the end of the run it copies the file it read into the repo as a snapshot, so the handbook renders the current draft and tracker rows can link to its sections.
4. The test result comes back to chat; rebuilds and confirmations return to step 1.
5. The file is committed when its module closes — every rule moved out, every build tested, every open item a row — and reopened in chat when a new issue hits. Until then HStemp is the master, the repo copy is a snapshot, and the file is outside the sync audit.

6.2 Where a commit goes

brand/tokens.css is a publicly-served governance file (CLAUDE.md Part B). The app/ row holds only while app/ has no deploy from main; it is rewritten before the first commit under any new arrangement.

7. The handbook

Public and ungated at handbook.happyship.us. A view, never a source.

Audience: Claude Code, when a task touches the public website.

Scope of this file. The public site at happyship.us, end to end: what it is for, what it may and may not contain, and how it is built and published. A task touching the website reads this file and needs no other, with two exceptions below.

Read SCOPE.md first; where the two conflict, SCOPE.md governs. Two things stay there because neither is the website's alone: deploy discipline for web/ and brand/ — every change under either takes a branch and a PR — and the product the site markets.

The website has no further documents of its own. The shared ones — visual, dictionary, backlog, conventions — are listed in SCOPE.md under Which document to open, and are deliberately not repeated here.

Not the application. That is APPLICATION.md, and nothing here reaches it.

1. Purpose

A public landing page introducing HappyShip: what it is, who it is for, and how to make contact. It is marketing for the product of SCOPE.md, not part of that product.

Published in two languages, English and Simplified Chinese, which are the same page in translation rather than different content.

The site performs no authentication, carries no application functionality, and holds no client data. The "Sign in" link of §2 is a signpost toward the application, not a login.

The website is not where the plan is published. It carries the public-facing statement as it stands at any moment. SCOPE.md carries both the internal and the external view, and both the short-term and the long-term design. The two are not expected to match.

1.1 Sharing a repo is not sharing a surface

The site links to the application and describes it; it does not share code with it. Nothing under web/site/ may import from, or depend on the contents of, app/.

That is a prohibition rather than an impossibility. A build step exists (§5) and could be pointed at app/ as easily as at brand/. It is not, and must not be — build.sh copies from brand/ and from nowhere else.

What the two surfaces do share is the brand, deliberately and in one direction: both read brand/, and neither reads the other. One repository, two deployments, two boundaries.

2. In scope

1. The landing page, in two language versions: English at / and Simplified Chinese at /zh/, sharing one stylesheet and one set of assets
2. Contact route — a published address, no form handling in v1
3. A "Sign in" link in the site navigation. It goes to the application, but has no destination for now — the application has no deploy
4. Cloudflare Pages deployment from main, running ./build.sh and serving web/site/
5. Apex and www DNS, www redirecting to apex

Content is [OPEN]. The client-facing wording of the retention rule (APPLICATION.md, tracked as BL-005) constrains it.

3. Out of scope

Anything not in §2 may not be in scope for the website. Do not build it, stub it, or scaffold for it. Stop and ask — and only start work on it after it has been added to this document.

Specifically not in v1: forms that submit anywhere, analytics, blog, pricing pages, any link into the application other than the "Sign in" link of §2.

This boundary is the website's alone. Work admitted to the application at APPLICATION.md is not admitted here, and the reverse.

4. What the site is

A static site, hand-authored. No generator, no framework, no package.json, no dependency install. No server and no database.

The rule is not "no automation" — it is that nothing has to be installed before the site can be seen. A cp clears that bar. A build system does not: it brings a dependency tree, a lockfile, a toolchain version, and a site nobody can render without installing something first.

5. The build step

There is one, and it is a file copy. build.sh at the repo root copies brand/assets/ and any brand/*.css into web/site/brand/. It transforms nothing: no file's contents are read, rewritten, minified, bundled or compiled, and the bytes that land under web/site/brand/ are the bytes in brand/. Plain POSIX shell, no dependencies, safe to run repeatedly.

build.sh exits non-zero when:

• the repo root looks wrong;
• brand/ or brand/assets/ is missing;
• brand/tokens.css is missing from the source, or has not reached web/site/brand/ after the copy;
• any brand/*.css fails to copy;
• the number of files copied does not match the number found, counted separately for the assets and for the stylesheets.

A broken copy therefore fails the deploy rather than publishing a partial one.

5.1 The tokens.css guard

brand/tokens.css is checked by name on both sides — in brand/ before the copy, in web/site/brand/ after it — never by asking whether the *.css glob matched anything.

web/site/styles.css carries no hex value at all: every color, space, radius, weight and font stack resolves against tokens.css. A tokens.css that does not arrive therefore does not degrade the site, it unstyles it — and a copy step that reported success while doing that would be the worst form of the failure.

A glob test starts passing the moment any other stylesheet exists, which is a guarantee about the wrong file. A count proves how many stylesheets arrived and never which.

The same reasoning is carried as a comment block in build.sh, beside the check. It is written twice on purpose: here for whoever is deciding what the build does, and there for whoever is about to delete a line that looks redundant.

5.2 Why a copy rather than duplication

This project publishes only web/site/, so a file above it has no URL on the website and the site cannot reference it. That is a fact about this project rather than about the repo: a second Pages project publishes handbook.html from the repo root (SCOPE.md), so a file above web/site/ can have a URL — just never one the website serves. The application has no such constraint either — it builds, and can read anything in the repo.

That left three ways to share the brand: duplicate the assets in git, move the published root up and expose the governance docs along with it, or copy. Duplication is two masters for one thing, which is a whole class of drift — the class that ends in a logo, or a token value, differing between the site and the app with nothing to say which is right. One shell command removes that class.

The copy now carries the entire visual system rather than a folder of images, which does not change the reasoning above but does change how much rides on the copy succeeding. That is why it is verified file by file rather than trusted to have run.

6. What the build carries

brand/assets/ and brand/*.css reach the live site, at /brand/….

Nothing else above web/site/ does. app/, brand/STYLE.md and the governance docs at the repo root are not copied and have no URL on this site — handbook.html has one from a project of its own, which this build neither produces nor knows about. That holds for anything added at those paths later, without a rule per file — and it does not hold for anything added to brand/assets/ or a new brand/*.css, which the build step picks up and publishes by design.

The copy is mechanical and runs at deploy with nobody reviewing it, which is what makes the branch-and-PR rule on brand/ load-bearing rather than cautious.

web/site/brand/ is generated output, not a source. It is gitignored, never edited by hand, and never committed. brand/ is its only master: an edit made to the copy is overwritten by the next build without warning, and a copy committed to git is the second master this arrangement exists to remove.

7. The published tree

web/site/ holds index.html, styles.css, robots.txt, site.webmanifest, assets/, zh/, and the generated brand/.

A root-relative path resolves against the output directory, not against the repo root. Pages publishes web/site/ as the URL root, so the web/ prefix never appears in a URL: /styles.css is web/site/styles.css on disk, and the same path works from /zh/ without a second copy of the file. How deep the output directory sits in the repo is invisible to the URL space.

8. Pages

Adding a page is adding a file. The build step copies assets; it does not generate pages, so no page passes through it and nothing has to be rebuilt to add one. Pages serves the file tree under web/site/ directly, so a subdirectory does not change that either.

The Chinese page is that property in use: one more HTML file, sharing the one served stylesheet and the one copy of assets/.

styles.css is never forked per language. Language-specific rules are scoped within it by :lang(). Two copies of the same rules drift. brand/tokens.css is not that fork — it holds values where styles.css holds rules, which is a split by kind rather than a second copy of anything.

There is no custom not-found page, and that is a decision rather than a gap. Pages resolves a single top-level /404.html and does no per-directory lookup, so a per-language copy is reachable only by typing its own URL. Pages serves its own default instead. Restoring a custom 404 is an amendment to §2 first, not a file someone puts back because they noticed it missing.

What this holds. The rules that reach every subject: language, how every date and time renders, and how every identifier is formed. A subject file points here rather than restating them.

What it does not hold. Any screen. Where a rule shows on a screen is that screen's file, and the check that proves it is walked there.

Status words. open the decision is not made · unbuilt decided, needs code · built code landed, not every check passed · done every check passed. Square brackets are not used.

1. Language

C001 built — Source language is American English on both surfaces. Simplified Chinese is the first target language. One language renders today.

C002 open — Whether Spanish and Vietnamese follow.

C003 open — The dictionary mechanism. DICTIONARY.md holds the EN–CN pairs for key terms; whether it is two-way — pairs pulled from what is built, hand-added pairs pushed back to the application — and what the push does is not decided. Key terms end consistent across both surfaces; filler words are not governed.

C004 unbuilt — User-facing strings are extracted for i18n, one file per locale, identical keys. A target language is generated from EN, never authored directly; a domain term the glossary lacks is added to DICTIONARY.md before generation. A key missing from a locale renders EN and is logged. Every string is written whole, never assembled from fragments. Language covers the interface and the PDF report.

C005 unbuilt — The document's language tag is a valid one — zh-Hans for Simplified Chinese, never cn.

C006 unbuilt — Carrier and service names, entity names and IDs are not translated.

C007 open — Whether charge-code labels are translatable strings.

2. Dates and times

C008 built — Every date and time is stored in UTC and displayed as the viewer's calendar day for the stored instant, with the zone named. No field is exempt. The viewer's zone is the machine's, read by the browser; nothing stores one. A date reads as yyyy-mm-dd wherever it is shown or entered, with no calendar to open; an entry field holds the typed yyyy-mm-dd and carries nothing beside or beneath it. A value agreed as a date renders on different days either side of a zone boundary; accepted as the price of one rule.

C009 built — Without JavaScript every date renders (UTC) and timestamps show UTC.

C010 open — Whether a stored zone preference arrives, so the no-JavaScript case can convert server-side.

3. Identifiers

C011 built — Three forms. An entityID identifies an entity. A typed ID identifies one record belonging to an entity and embeds the entityID that owns it. A reportID identifies one comparison run and is printed on the report.

C012 built — An entityID is four characters — one letter A–Z, then three from the safe set. It is generated by HappyShip at entity creation, randomized and collision-checked at issue, never supplied by a user, and it never changes.

C013 unbuilt — HS is reserved as an entityID prefix for HappyShip's own entities, the last two characters the country code of a branch office — HSUS, HSCN, HSHK — seeded rather than generated. No generated ID begins HS, and the database refuses a client entity whose ID does.

C014 built — The safe set governs the generated characters only — positions 2 to 4 of an entityID and a typed ID's five-character suffix. It excludes the characters that confuse visually: 0/O, 1/I/L, 2/Z, 5/S, 8/B.

C015 built — A typed ID is eleven characters — an entityID, a hyphen, one type letter, then five from the safe set. It is unique within one entity and one type, and stored with the hyphen. The type letter is chosen, not generated, and takes any letter or digit.

C016 built — A type letter is registered in the catalog, live or reserved. Live means a table stores identifiers of that type and constrains the letter; reserved means the letter is claimed and no table accepts one. A generator reads the catalog before minting. A table that stores a typed ID constrains its first four characters to the owning entity. A reserved letter can be added or removed freely; a live letter cannot.

C017 unbuilt — A reportID is eighteen characters — the requesting entity's entityID, a hyphen, the run's date as YYYYMMDD, a hyphen, one type letter (R rate-for-rate, S shipment-cost), and a three-digit counter of that entity's runs of that type on that date. ABCD-20260910-R001. The safe set does not reach it: nothing in it is drawn.

C018 unbuilt — An ID that appears on a delivered PDF is never reissued, even after the file it named is purged. An issued-ID ledger holds it.

C019 open — A ship-from location's identifier is a plain counter today, outside this scheme. It becomes real when warehouse and fulfillment services arrive.

What this holds. Everything about entities: what an entity is, the rules around its fields, how logins and ship-from locations work, and the two screens. One subject, one file.

What it does not hold. Anything spanning every subject — security, migrations, sessions, the screens every subject shares, the fields themselves, and the checks that prove what is built. Those live in the files that own them.

Status words. open the decision is not made · unbuilt decided, needs code · built code landed, not every check passed · done every check passed. Square brackets are not used.

1. What an entity is

E001 built — An entity is the isolation boundary. No client can see another client's data, on any path. HappyShip reads and writes across clients through internal paths. A login is the identity; the entity is the boundary.

E002 built — There are two entity types, internal and external. Each has its own surface, and the band's color says which (brand/STYLE.md).

No login can do what another login of the same entity cannot. Language is the only thing held per login (home.md). The primary login differs in what may be done to it — HappyShip alone changes its address, and no client login deletes it — never in what it may do.

1.1 Who is internal

A login bound to HappyShip is internal; every other belongs to a client. No address domain is checked.

An internal login may create and manage entities — its own and every client's; manage master data, templates and reference standards; and manage accounts, contracts, balances and which services an entity holds.

1.2 Who is external

A client is created to use one of the services HappyShip provides, free or paid. An external login may manage its own entity profile, its logins and its ship-from locations; view its own account balance; and use the services its entity holds.

Buyer and seller are not stored roles. No role field, no role enum, no role-based branches in the data layer, no role-based permission checks. What a client may do is what HappyShip authorized its entity to do; what it may see follows ownership and publication. One entity commonly acts as both.

The services a client may hold are Compare rates, Manage rates, Audit invoices and Track shipments (SCOPE.md). What each costs, whether it is free, and what a discount may do to it are RULES-HS-CHARGES.md.

2. What an entity carries

2.1 Identity

Fields: DATA.md → entities — entity_id, company_name, nickname, created_at, updated_at.

The entityID's form — four characters, the HSXX reservation, that it never changes — is common.md §3.

E005 unbuilt — A nickname may be duplicated. Two entities may carry the same nickname. Entering one another entity already holds raises a reminder rather than a refusal.

E006 done — A company name resolves to one client. A name a live client already holds is refused, at creation and at edit alike. Case does not distinguish two names; whitespace does. It does not reach HappyShip's own branches.

E007 built — created_at and updated_at are shown on both screens, beside the entity ID rather than among the profile's fields. Neither shows before the first save. created_at is also a column on the internal list (§4.1).

Both are timestamps: stored UTC, displayed in the viewer's local zone, with hh:mm.

2.2 Relationship and commercial

Fields: DATA.md → entities — country, company_address, currency, hs_branch, contact_name, contact_phone, hs_point_of_contact, payment_method, internal_notes.

E008 built — A company address is required once a contract is signed. Before that it may be empty.

E010 built — Country is the company's headquarters address country, chosen from a pre-seeded list HappyShip adds to by hand when needed. US, CN and HK are the initial three; others are not offered.

E011 built — Currency is what the client pays HappyShip in, chosen from a pre-seeded list; USD and CNY are the initial two. Country does not constrain currency.

E012 done — A HappyShip entity carries no currency. The field is absent on its page rather than empty, and the database requires a currency of client entities alone.

E013 done — An HS branch is the HappyShip office holding a client relationship and collecting its fees (RULES-HS-CHARGES.md). A HappyShip entity names no branch of its own.

The branch is set independently of the country and may change. What a change does to fees already collected is RULES-HS-CHARGES.md.

E014 built — Payment method follows the currency, not the country — USD pays by Stripe or ACH, CNY by ACH. Free text holds it.

The entity's primary email is also a login — the primary login, held in logins (§2.5). The entity record carries no email field of its own.

2.3 Contract

Fields: DATA.md → entities — contract_signed_on, contract_expires_on, document_link.

E018 done — A contract is signed or it is not, and one control says which, with a signed date and an expiry date beside it. Set is signed, empty is not; an expiry date requires a signed date, and the database enforces that. Today HappyShip sets all three by hand. In a later stage they derive from the signed online template — the template, the client's I agree, what a term does to the system, and what instant an expiry resolves to are a contract module's.

E068 built — The document link is an entry pointing to a folder, not the contract alone.

2.4 Entitlement

Fields: DATA.md → entities — service_compare, service_manage, service_audit, service_track.

E022 open — A contract and a payment method gate the services. A service is not switched on for an entity that has neither. In phase 1 both are established by hand, so the gate is HappyShip's own discipline rather than a check the screen performs. Whether it becomes a check is open.

E023 done — Each service is authorized independently. HappyShip grants and removes them one at a time, and holding one says nothing about holding another.

E026 built — Manage rates gates the whole rate-management surface, not one act inside it. Without it a client cannot store a card, publish one, or derive a sell rate from a buy rate (L3 and L4, future).

E027 unbuilt — Removing Manage rates takes the rate library away from the client. Its published cards are withdrawn from the pool, and it can no longer reach the cards it stored. HappyShip keeps those cards where it chooses to.

What else a card must satisfy before it publishes is the Rate module's.

These four booleans are what HappyShip charges against (RULES-HS-CHARGES.md). Audit invoices and Track shipments are forced off by hand in phase 1.

2.5 Logins

Fields: DATA.md → logins.

E028 built — A login is always an email address and belongs to one entity. The address is unique across the whole system, not only within an entity.

E029 done — An address is matched without regard to case and stored lowercased. The database enforces it — logins_email_check refuses a mixed-case address.

E030 built — An entity holds at most three logins. Adding a fourth means deleting one first.

E031 built — The primary login is created from the address HappyShip enters when the entity record is first saved, and it is marked as primary. The marker is enforced by the database, one per entity.

E032 done — The primary login always exists and always works. Its address is changed by HappyShip and never by the client; the client cannot delete it. A client whose only mailbox has failed reaches HappyShip through the contact form.

E033 done — Every login after the first is the owning entity's to add and remove. HappyShip adds and removes none of a client's.

E034 built — No login's address is edited. Correction is delete and recreate. The primary login is the one exception, and only HappyShip may change it. The change is an update to the existing login, never a delete and recreate — the row keeps its identity.

E035 built — HappyShip adds its own logins the same way, on its own entity page. What it cannot do is manage a client's. A HappyShip entity's primary login is seeded with the entity rather than entered.

E036 built — Deleting a login ends its session immediately, checked per request rather than at expiry. A deleted address is free to be registered again. Cards that login published stay published.

Deleting one login is the entity's own act; deleting the account is a request to HappyShip (§3).

E037 unbuilt — Some actions store which login performed them, with a timestamp.

The sign-in screens, the welcome and deletion mails, the unregistered-address page and the contact-us recovery path are home.md's. This file keeps what a login is.

2.6 Ship-from locations

A ship-from location is an origin the entity ships from, held against the entity and listed on its page. One entity, many locations.

Where the entity ships from is not a field on the entity record; the company address (§2.2) is the entity's own address.

Fields: DATA.md → ship_from_locations.

E038 unbuilt — A location may carry a name the client chooses. It labels rather than identifies — two locations may hold the same one, and a location without one is known by its address.

E039 unbuilt — The location list is what a rate card's named regions draw on. A card entering the pool names regions, never addresses: each location resolves to the region its address falls in, and a card naming particular regions selects among those. An entity cannot name a region it has not said it ships from.

E040 unbuilt — The region is derived from the postal code, by nobody's hand. HappyShip maintains the region list and the postal-code-to-region mapping (the Master data module), and a location takes the region its postal code maps to. HappyShip writes the mapping, never the region on a location.

The region picker on the add form is a stopgap. It goes when the mapping lands and the column becomes nullable. Nothing should be built on top of it.

E041 unbuilt — An unmapped postal code leaves the region empty, and empty reads as unmapped. The location still saves, and HappyShip is flagged on its own dashboard to add the mapping. Empty is NULL, not a value. The column is NOT NULL today, so this is a new migration.

An unmapped location does nothing until it is mapped. It cannot enter the comparison pool. The client cannot clear the state — the region is read-only to it and the mapping is HappyShip's. A screen showing an unmapped location says that.

HappyShip may remap a postal code to another region. Nothing on a location changes when it does: the location holds the code and the mapping holds the region.

A location's identifier is a plain counter today, outside the ID schema. It becomes real when warehouse and fulfillment services arrive.

An entity holds as many locations as it needs. There is no ceiling.

E042 built — The client writes them; HappyShip reads them. HappyShip adds and removes none.

3. Creating and deleting an entity

E043 open — HappyShip creates entities in phase 1. Self-registration comes in a later phase; which one is open. When it comes, an entity anyone created arrives unvetted and is not active until HappyShip vets it. A free service is the exception: an entity agreeing to the terms could use a free service straight away; whether that exception is taken is open.

E044 done — Creation takes every mandatory field. There is no separate create screen: the Create new button opens the entity page itself, empty, and the first save registers the record and mints the entityID. A save missing a mandatory field is refused exactly as a later edit would be.

E045 built — An entity is deleted on the client's request, and HappyShip executes it. A client may request deletion at any time but cannot delete its own account. The client does not clear its logins first: every login goes with the entity in one act. The confirmation that the account is fully deleted is emailed to the primary login.

E069 unbuilt — Deletion is gated. One click does not delete an entity; HappyShip confirms the deletion in a second step before it executes.

E046 unbuilt — A request with a balance left gives the client a choice between a hard stop and a soft stop. What each does to the balance, the refund and the remaining service is RULES-HS-CHARGES.md.

4. Screens

What follows is the rules a screen has to satisfy, not a description of it.

4.1 The entities list — internal

One button opens an empty entity page. No inline create form, and no create screen of its own.

E047 built — Columns — entity ID, company name, created on, last login, AR collected, HS branch, action. Action carries Edit and Delete.

E048 done — Every column sorts except entity ID and action.

E049 done — A HappyShip entity names no branch of its own, collects no AR, and is not deleted.

E050 unbuilt — Counts are computed, never stored — AR collected and last login among them. entity_counters is dropped with migration 0034. Last login is the most recent session the entity's logins hold.

4.2 The entity page — internal

E051 done — No field is pre-filled with a guess. Country opens on its placeholder like every other mandatory picker.

E052 done — Mandatory fields are marked, by the convention brand/STYLE.md sets.

E053 done — A refusal marks the field and nothing else. Every refused field takes the same border, and the screen says once at the top that something was refused.

E054 done — A field that is mandatory only sometimes carries the mark only then. The contract dates are required once the contract is switched to signed; the company address is required once a contract is signed. brand/STYLE.md owns what the mark looks like; when it shows is this screen's.

E055 built — The field holding the primary login is labeled Primary email, here and on the client's page.

E056 built — One save control writes the profile, the services and the primary email, and it stands at the upper right of the page head, above both columns. The Services card's switches take effect only when it is pressed. The ship-from card writes nothing here. The logins card writes through its own controls on a HappyShip entity and is read-only on a client's, whose primary login changes through the Primary email field this control saves.

The entity ID carries the two timestamps beside it (§2.1), as on the client's page.

The services panel does not apply to a HappyShip entity.

E057 unbuilt — A HappyShip entity shows Business At Glance in place of the services panel: client count and how many pay, revenue collected in total and this year, rates by last mile, reference standard and warehouse, and invoices audited and in queue.

4.3 The entity page — client

E058 done — The client sees its own entity page. Company name, country, company address, HS branch, the contract, payment currency, HappyShip's point of contact, the document link and the primary email are read-only. Contact name and contact phone are the only fields a save writes.

E059 done — A read-only value is stated, never dressed as a control. A state renders as a pill — country, HS branch, payment currency, the contract's signed state, each service. A text value renders as text. Neither is a disabled input. An unset read-only value shows an em dash.

E060 built — Nickname and internal notes are absent, not hidden. The client reads its own account balance on this page. Nothing computes a balance yet, and §2.2 carries no field for one.

E061 done — The ship-from card states how many locations the entity holds, and the logins card how many of the three.

E062 built — There is no time zone control on this page. Dates render in the zone the viewer's machine reports (common.md §2). Language is not here either — it is in the navigation band, on every page.

E063 built — The right column runs account balance, then logins, then ship-from locations. The left column holds the profile and the contact details alone. A control adding a row stands above the list it adds to, on the locations card and the logins card alike. A location shows its name where it has one, and its address, city, state and zip.

The mandatory mark and the refusal treatment are §4.2's, unchanged.

The entity ID carries the two timestamps beside it (§2.1).

E064 built — The profile's order groups what is read together. HappyShip's point of contact stands beside the HS branch. Payment currency stands beside the contract, and the contract's signed and expiry dates share one row. Contact details stay at the foot of the card.

E065 done — The logins card lists every login the entity holds, the primary among them. The primary is marked and the client cannot delete it; the client adds and removes the rest, within the ceiling of three (§2.5).

E066 done — The services card and the glance card are not on this page. The client's landing states what the entity holds (home.md).

4.4 Dates and times

The rule is common.md §2. Its checks on these two screens are walked here.

5. What this file hands to other files

Claims made here that another file has to carry. Recorded so they are not lost between a sentence in this file and a file that does not exist yet.

To the Rate module — no file yet

To a contract module — not started

To RULES-HS-CHARGES.md

To the Master data module — no file yet

To home.md — the surface before the subjects

To the ID schema module — no file yet

To RULES-<leg>.md

6. What this file replaces

APPLICATION.md and BUILD.md sections 1.1.1, 1.1.2 and 1.1.3 point here until they are deleted.

What this holds. The surface a person meets before any subject: the landing on each surface, the navigation band that frames every page, sign-in, and the one setting a person holds for themselves — language — with the one rule governing how every date and time in the application renders. One subject, one file.

What it does not hold. Anything a subject owns. A count stated on a landing is computed from a subject's data; this file says what the landing states, never what the subject is.

Status words. open the decision is not made · unbuilt decided, needs code · built code landed, not every check passed · done every check passed. Square brackets are not used.

1. Navigation

H001 built — A landing is where a signed-in person arrives, and it is per surface. A landing is triage: it states what is there and routes to it. Nothing is created, edited, deleted or computed on it beyond the counts of §4.3. The client landing exists; whether the internal surface gets one is §5.

H002 unbuilt — One root per surface, and neither leads to the other. No link runs from a client page to an internal one, or back, and neither surface renders for a session bound to the other: the route refuses, and the template refuses again where the page is drawn. A HappyShip login reaches no client screen, /rates included; the internal band's Rates is a placeholder until an internal rates screen exists.

H003 built — The band carries four things and no more: the address as text, a language picker, Manage Account, and Sign out. It is the same band on both surfaces, on every page including the sign-in pages; only the field beneath it differs, per brand/STYLE.md. A control on the band takes its ink, border and contrast from the environment layer.

H004 done — Sign out submits; it is not a link.

1.1 There is no settings screen

H005 built — Language has no screen of its own. It is set in the band.

H006 built — Changing the language takes effect on the next page rendered, and changes nothing for any other login of the same entity.

H007 open — Whether a language change re-renders the page the person is on.

H008 unbuilt — Each control says, where it sits, that the setting is the login's own.

2. Sign-in

H031 unbuilt — Passwordless, in two screens. A person enters an address, then the code emailed to it. There are no stored passwords and no reset flow. The three screens are built as a shell — the address page, the code page and the not-registered page — and nothing yet generates, sends, stores or checks a code. The code's mechanics are ARCHITECTURE.md's.

H032 built — There is no separate sign-up. A first visit and every later one are the same two screens, and an address that is not registered cannot sign in.

H033 built — Signing in is agreement to the terms and conditions and the privacy policy, and the first screen says so. This holds for every client, free or paid.

H034 done — An unregistered address gets a page, not a dead end. Where an entity exists for that address, the page asks the person to contact their entity's owner; where none does, it invites the business owner to contact HappyShip. Each next step sits under the path it belongs to.

H035 unbuilt — A delivery failure has one recovery path: contact us — an online form that emails HappyShip. HappyShip then changes the primary address (entity.md).

H036 built — A session survives a browser close and ends on its own, and signing out is the only way a person ends their own.

H037 unbuilt — Two mails are sent outside a session, so both are EN: the welcome on registration and the notification on deletion. Neither is withheld to avoid the other. Nothing sends mail today.

H038 open — What the two sign-in screens look like, and what the unregistered-address page says in words.

H039 open — Where sign-out lands once a sign-in page exists, while /dev/session still exists. It redirects there today.

3. Language and dates

3.1 Language

The language rules are common.md §1 — which languages, the glossary, how a locale is built and what is not translated.

H009 built — Language is per login, not per entity. Two logins in one entity may differ in it.

H015 built — The picker changes the language on choice, with no second control. When i18n lands, the picker either warns before it changes or takes back a control that submits (WCAG 3.2.2). The code screen keeps naming the address it was sent to when the language changes.

3.2 Dates and times

The one rule is common.md §2 — stored UTC, shown as the viewer's calendar day with the zone named, yyyy-mm-dd everywhere. It reaches every screen, and the checks that prove it are walked on each.

H010 built — A person does not set a time zone, and there is no control for one. The viewer's zone is the machine's, read by the browser.

H018 open — Whether the internal screens disclose the zone boundary beneath a date. The line was withdrawn from both surfaces on a client-side argument; HappyShip reads entities across zones.

4. The client landing

4.1 The screen

H021 built — It is the first screen after sign-in, and it is four cards. Each names a service, states whether the entity holds it, carries that service's figures where they exist, and offers the route or names the path.

H022 built — The heading is the entity's name.

H023 built — A held card takes the environment's action fill; a card for a service not held does not.

H024 built — Nothing else is on this screen. No entity details, no locations, no logins, no balance: all of those are behind Manage Account.

4.2 The service cards

H025 done — Four cards, one per service, named as SCOPE.md names them — Compare rates, Manage rates, Audit invoices, Track shipments. All four show, held or not. A service is held or it is not, and the card says which; two states and no third.

H026 built — A held service carries the route to its own surface. Compare rates goes to rate and shipment upload; Manage rates to rate upload.

H027 built — A service the entity does not hold offers no control. The card states the fact and names HappyShip's point of contact as the path.

H028 done — A function not admitted is inert: a label, not a route, a stub, or a screen that explains itself. Audit invoices and Track shipments are the two today.

4.3 What it counts

H029 unbuilt — The landing counts per service, not per entity. Each card carries its own figures, shown only where the entity holds the service. Until a counter exists, a card states no figure.

The ship-from count and the account balance are the entity page's (entity.md).

5. The internal landing

H030 unbuilt — The internal landing is four cards, like the client's: Manage entities, Manage master data, Manage ledger, Audit invoices. Each names its function and carries the route to it. Manage entities routes to the entities list (entity.md §4.1), which exists; the other three route to surfaces not yet built. Today an internal login lands on the entities list.

H040 open — Whether Business At Glance moves here from the HappyShip entity's page (entity.md).

6. What this file hands to other files

7. What this file replaces

APPLICATION.md §9's two paragraphs on the client's home and §2.4's sentence on navigation point here until that file is retired.