Domain Specs

When to read a domain spec

• Implementing or changing behavior of a backend domain (preview, modelling, billing, etc.).
• Reviewing code for correctness against documented behavior.
• Adding or changing endpoints or auth rules.
• Debugging or clarifying integration between domains (internal API).
• Writing or updating a domain spec so it stays consistent with existing ones.

What to describe when writing or extending a domain spec

Follow the structure and level of detail of the existing domain specs (preview, billing, modelling). Each section uses requirements (SHALL/MUST) and scenarios (WHEN/THEN).

1. Header and intro

• Title: # Spec: <Domain> domain (backend)
• One paragraph: What the domain does and how other domains integrate (internal HTTP APIs). Example: "Previews are images generated or uploaded… Other domains (e.g. billing, modelling) integrate via internal APIs."
• Scope: Backend only. Audience: developers. Use: verify implementation correctness.
• DDD compliance: One sentence that the implementation SHALL follow the structure and patterns in openspec/specs/ddd-implementation/spec.md, and that this spec defines behaviour and API contracts; the DDD spec defines how the domain is implemented. Link: [DDD implementation spec](../ddd-implementation/spec.md).

2. Authentication and access

• Internal controller: Internal API key accepted only on a dedicated internal controller (e.g. preview/internal, billing/internal). List endpoints that live there and accept the internal key; state they do NOT require JWT.
• Main controller: User/admin routes require JWT (and admin role where applicable); internal API key SHALL NOT be accepted (401 if only internal key). List which endpoints are main-only.
• Public endpoints: If any (e.g. get costs, view image), state they require no auth.
• Admin: Endpoints that list or manage all resources require admin role (or admin API key); non-admin gets 403. Internal API key does not grant admin.
• Scenarios: For critical cases: WHEN client calls X without JWT / with only internal key / without admin THEN 401 or 403; WHEN with valid JWT or internal key THEN success. One scenario per requirement is enough; add more for subtle cases (e.g. internal vs main controller).

3. User-facing API

• One requirement per capability (e.g. generate preview, get my wallet, redeem voucher). Each requirement: endpoint (method + path), body/query when relevant, auth, and expected success response.
• Scenarios: Happy path (valid input + auth → 200/201 and response shape); validation (missing/invalid input → 400); business rules (e.g. cannot afford → 403); not found → 404. Include edge cases that affect API contract (e.g. idempotent purchase, already purchased).

4. Admin API

• Requirements for list-all, get-by-id, create/update/invalidate (e.g. vouchers). Auth: admin role or admin API key; otherwise 403.
• Scenarios: admin succeeds; non-admin gets 403.

5. Internal API

• If the domain exposes an internal API: Dedicated internal controller; list endpoints with path, method, body/query, auth (internal API key only), and response shape. State that callers are other backend domains.

6. Entity and status lifecycle (and domain entities if needed)

• Status values: List allowed statuses and which are terminal (e.g. success, failed). Transitions: WHEN creation / work start / success / failure THEN status and optional timestamps. Invariants: e.g. terminal status is immutable; no transition from success/failed.
• Domain entities (if the domain has rich aggregates, e.g. billing): For each aggregate (Wallet, Transaction, Purchase, Voucher): purpose, identity (e.g. one per user, uniqueness keys), lifecycle (created, updated, terminal states), operations (e.g. reserve, confirm, release, spend), invariants (idempotency per actionId, balance from transactions only).

7. Data returned (DTO)

• DTO fields: For main resources (e.g. preview, model, wallet), list at least: id, userId (if applicable), status, createdAt, and domain-specific fields (e.g. credits, transactions, url, downloadUrl). Note optional fields (e.g. estimatedProgress, errorMessage when failed).
• Key response shapes: e.g. GET /costs → { preview, model, modelDownload }; internal can-afford → { canAfford: boolean }; purchase-download → { ok: true, alreadyPurchased?: boolean }. For errors (e.g. 402), document body shape (e.g. code: 'insufficient_credits') so callers can map to user-facing messages.

8. HTTP and error contract

• Errors: 401 (missing/invalid auth), 403 (forbidden, e.g. non-admin or insufficient credits), 404 (resource not found), 400 (invalid input), 402 (payment required) where applicable. One line per code and when it is used.
• Success codes: 200 OK for most reads/updates; 201 Created for create endpoints; list which endpoints return which.

Consistency and maintenance

• Keep specs up to date: Whenever implementation details change (new or changed endpoints, auth rules, DTOs, error codes, or behavior), update the corresponding openspec/specs/<domain>/spec.md so the spec remains the single source of truth. Drift between spec and code makes verification and onboarding harder; treat spec updates as part of the change, not optional.
• Terminology: Use the same terms across the spec (e.g. “internal controller”, “JWT”, “admin role”). Match naming to the codebase (e.g. canAfford, hasPurchased, purchase-download).
• Cross-references: When the domain integrates with another via internal HTTP, document request/response contracts so caller and callee specs stay aligned.
• Do not duplicate DDD structure: Do not re-specify layout, seedwork, or module wiring; link to openspec/specs/ddd-implementation/spec.md and keep this spec focused on behavior and API contracts.
• When adding a new section: If the domain has a distinct surface (e.g. “Public view API” for preview images), add a numbered section with the same requirement/scenario style.

Quick reference: spec location and examples

For full requirements and scenarios, read the spec file for the domain you are working on; use this skill to find the right file and to know which details to include when writing or extending a spec.