Document billing workspaces in architecture and specs

Reflect the new isolated-workspace feature across the design docs and the
product spec: testing isolation guidance, the storage architecture note,
functional requirement FR-010, non-functional requirement NFR-008, the API
contract Workspaces section, the data-model scoping note, and tasks T147.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: midagedev

docs/ARCHITECTURE.md

@@ -67,7 +67,14 @@ Initial default:
 - SQLite for local app state
 - in-memory option for unit tests
 
-Tables:
+One running server can host several isolated billing datasets. The implicit
+`default` workspace is backed by the configured `database_url`; each named
+workspace (selected per request via the `X-Billtap-Workspace` header or
+`workspace` query parameter) opens its own SQLite database lazily under a
+sibling `workspaces/` directory and gets an independent API handler, so its
+billing state, webhooks, idempotency keys, and test clocks stay isolated.
+
+Tables (per workspace):
 
 - customers
 - products

docs/TESTING.md

@@ -81,6 +81,11 @@ Fixture ergonomics for integration tests:
 - assert expected objects through `POST /api/fixtures/assert`
 - keep fixture IDs stable for customer, product, and price setup
 - use fixture `runId`, `namespace`, `tenantId`, and `ref` metadata to isolate repeated local/CI runs
+- for stronger isolation, run parallel suites against separate Billtap
+  workspaces instead of restarting the server between sets: send
+  `X-Billtap-Workspace: <name>` (or `?workspace=<name>`) so each suite gets an
+  independent dataset, while unselected requests keep using the `default`
+  workspace; `GET /workspaces` lists what exists
 
 Integration diagnostics for failed app runs:
 

specs/000-product/contracts/api.md

@@ -16,6 +16,26 @@ Process health.
 
 Storage and worker readiness.
 
+## Workspaces
+
+One running server can host several isolated billing datasets. Every `/v1`
+and `/api` request resolves a workspace before dispatch:
+
+- A request with no selector uses the `default` workspace, backed by the
+  configured `database_url`. This keeps existing integrations unchanged.
+- A request may select a named workspace with the `X-Billtap-Workspace`
+  request header or the `workspace` query parameter. Named workspaces are
+  created on first use, have their own storage, and are isolated from each
+  other and from `default`.
+- The resolved workspace name is returned on the `X-Billtap-Workspace`
+  response header. An invalid workspace name returns `400`.
+
+### `GET /workspaces`
+
+Lists known workspaces (the default, any opened this session, and any whose
+database file already exists). Returns a `list` envelope of `workspace`
+objects with `name` and `is_default`.
+
 ## Stripe-like API
 
 ### Customers

specs/000-product/data-model.md

@@ -1,5 +1,11 @@
 # Data Model
 
+All entities below are scoped to a single workspace. A server hosts the
+implicit `default` workspace plus any named workspaces; each workspace has its
+own isolated store, so the same entity id may exist independently in different
+workspaces. Workspaces are an instance-level partition and are not themselves
+persisted rows — see `contracts/api.md` for selection and listing.
+
 ## Customer
 
 - id

specs/000-product/spec.md

@@ -117,6 +117,11 @@ Acceptance criteria:
 - FR-007: Create, retrieve, confirm, fail, and list payment intents.
 - FR-008: Create, retrieve, update, delete, and list webhook endpoints.
 - FR-009: Create, retrieve, and list events.
+- FR-010: Serve isolated billing workspaces from one running server. Requests
+  with no workspace selector use the backward-compatible `default` workspace;
+  a request may select a named workspace via the `X-Billtap-Workspace` header
+  or `workspace` query parameter to get an independent dataset, and the known
+  workspaces are listable.
 
 ### Hosted UI
 
@@ -177,6 +182,8 @@ Acceptance criteria:
 - NFR-005: No real card data is stored.
 - NFR-006: Contract behavior is fixture-backed.
 - NFR-007: Profile-specific behavior is fixture-backed and does not require production payment credentials.
+- NFR-008: Named workspaces are isolated at the storage boundary so parallel
+  test suites do not need a server restart or shared-state reset between runs.
 
 ## Non-Goals
 

specs/000-product/tasks.md

@@ -269,6 +269,7 @@ Gate:
 - [x] T144 Capture the public simulation capacity backlog for regression-driven fixture and scenario expansion
 - [x] T145 Expand customer history, subscription pause/resume, and payment-method attach/detach simulation routes
 - [x] T146 Add browser-facing public base path and forwarded-prefix support
+- [x] T147 Add isolated billing workspaces selectable per request so parallel test suites share one server
 
 Suggested agents: