hora-spec-backend
Stage 4 of /hora-spec. Declare the repositories and servers, then design the data model, the operation list and the background jobs that every stage-1 use case can be walked against. Invoked by /hora-spec, or directly.
openreachtech · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add openreachtech/hora-core --skill hora-spec-backendAbout this skill
name: hora-spec-backend description: Stage 4 of /hora-spec. Declare the repositories and servers, then design the data model, the operation list and the background jobs that every stage-1 use case can be walked against. Invoked by /hora-spec, or directly.
hora-spec-backend
Stage 4 of /hora-spec. Design what holds the data, what operates on it, and what runs outside the request — and prove, use case by use case, that the result can serve them.
Read ../hora/references/structure.md and ../hora-spec/references/principles.md first. ../hora-spec/references/stages.md is the authority on this stage's exit condition, ../hora/references/spec-format.md on the format of every table written here, and ../hora/references/asking.md on how anything is put to a person.
This stage holds no design rule of its own. How a table is shaped, how an API schema is named, where a job belongs and how a queue is tuned all live in the @openreachtech/hora-skills-ort-* packages. Invoke the skills the delegates table names and read them — never restate one of their rules here.
What this stage reads
This is the stage that reads the backend properly: the migrations, the models, the API schemas, the REST routes, the job definitions and the entry points, at depth.
The whole existing data model and operation list goes out as checks, batched per area — one for the tables, one for the operations, one for what runs outside the request. A person confirming the fourteenth table in a row has stopped reading (../hora-spec/references/investigation.md).
A check on the data model says what the product remembers, not which columns hold it (../hora/references/asking.md, "What changes for the person").
A feature listed under Baseline: inventoried still owes its tables and its operations a row each here. The section itself carries a name and one line (../hora/references/spec-format.md, "baseline") — but its tables are in the database everything designed here has to fit around, and its operations sit on a server stage 6 has to state a caller for. It costs almost no exchanges, since those rows sit inside the batched checks above.
| Read it, put it up as a check | Ask, or propose |
|---|---|
| which tables exist, and what columns they hold | why the model came out that way, and what it rules out |
| which operations exist, and what each returns | who each operation is for |
| which work already runs outside the request path | whether work that runs in the request still belongs there |
| what the existing tests assert | whether what they assert is what anybody wanted |
A shortfall found while reading is a proposal, never a check. "There is no index on this foreign key" states a fact; "add one" is this stage's own thinking.
What this stage decides
which repositories exist, and which servers run inside the backend
one endpoint switched on role, or an endpoint per audience
what tables hold, in logical terms
which operations exist, of which kind, against which server
which processing does not run inside a request, and why not
What it must not decide
| Whose it is | |
|---|---|
| a new use case, or a use case's wording | stage 1 |
| whether a feature is in this release | stage 2 |
| a user count, a retention period, an availability target | stage 3 |
| which screen calls an operation | stage 5 |
| who may call an operation | stage 6. This stage writes the operation; stage 6 writes its caller |
| a class name, a table name, a column name that lint has to accept | /hora-plan, against the lint rules |
| the migration, the model, the resolver, the job class | /hora-build, at checkpoints 3 to 7 |
The order inside this stage
1. The repositories, and the servers inside the backend
2. Roles on one endpoint, or endpoints of their own
3. The data model
4. The operations, per server
5. What runs outside the request
6. Walk every stage-1 use case against 3, 4 and 5
Step 6 is the exit condition, not a review. A data model that is internally tidy and cannot represent one stated use case passes every other check in this document.
1. The repositories and the servers
Declared, never assumed — /hora-setup reads this table and stops without it.
| Repository | Origin | Role |
|---|---|---|
| `acme-backend` | `<a backend origin>` | the API and jobs (holds the DB) |
| `acme-frontend-employee` | `<a frontend origin>` | the employee-facing screens |
| `acme-frontend-admin` | `<a frontend origin>` | the admin screens |
### 2.1 Servers
| Server | protocol | consumer |
|---|---|---|
| `employee-api` | (the default style) | `frontend-employee` |
| `admin-api` | (the default style) | `frontend-admin` |
| `worker` | — | an API server in the same repository (no contract needed) |
Origincomes from the origin catalog, and so does each origin's row count (../hora/references/structure.md, "How to find the origin catalog"). A count outside an origin's stated bounds — a second backend, say — stops the run- Frontends are zero or more. An API-only release declares none, and stage 5 is then not applicable
- Names read
<myproject>-<role>-<purpose>, from stage 1's project name - The server table is the unit contracts are cut from, so it is always written.
consumerdecides whether a contract exists at all - A repository that already existed gets the optional
Directorycolumn, and/hora-setupthen never clones it
Everything else about this table is in ../hora/references/spec-format.md.
2. Roles on one endpoint, or endpoints of their own
The most consequential choice this stage makes. ../hora-spec/references/principles.md holds the full decision table; the three cases in one line each:
| The situation | What to do |
|---|---|
| roles come and go | one endpoint, switched on role |
| genuinely different entities — a different login, a different lifecycle | **separate endp |