Skip to main content
Version: v1.0.0(int)

v1.0.0 — Implementation plan

The design is locked across L1 (data) → L2 (components) → L3 (workflows) → L4 (public API) → L5 (clients). The tasks below are the build-out — one per layer, in the order they need to land so each task can rely on the one before it.

Tasks​

  1. Implementation kickoff. Decide and document two strategies before any code lands:

    • Test strategy — what happens to the existing test suite as old code gets replaced (keep, port, or delete-and-rewrite per area).
    • Old/new code coexistence — build new code in parallel and switch over at the end, or replace as we go. The split-deploy + scripted weekend cutover stance for the database (Task 2) makes parallel coexistence the natural default for the rest of the stack too.

  2. Database migration. Apply the data model from L1 to the develop-1.0.0 database — including data movement, not just DDL. The current plan is to run the new stack in parallel against a fresh DB and ship a tested migration script as the cutover step; final ordering, backfill, validation queries, and rollback strategy get decided in this task.

  3. Implement the domain components (L2). One task per component. Thin DB-access APIs, no constraints — they belong in L3. Each component takes a conn parameter; tenant context flows ambient via SET LOCAL app.org_id on the connection.

  4. Implement the L3 workflows (L3). One task per workflow defined in L3. Cost cascade workflows land last because they touch the most components. Every workflow opens its own withTransaction and owns idempotency where needed.

  5. Implement the L4 routes (L4). Refactor the Express route handlers against the public API designed in L4. Author Zod schemas in @pharus/api-contracts and register routes with @asteasolutions/zod-to-openapi; the build step emits openapi.json as the canonical machine-readable artifact (see the L4 Toolchain section). CI checks for spec drift on every push.

  6. Migrate frontend logic (L5). One task per page that currently carries logic — derived from the L1 user-actions inventory. Run orval against the emitted openapi.json to generate the typed fetch client + TanStack Query hooks; old frontend/src/api/* modules get replaced page-by-page as their owning page migrates.

  7. Frontend restructure. Once logic is out, clean up the frontend — API client layer, state management, component organization.

  8. Cleanup. Delete the old db/ modules, old route files, and any other code made dead by the implementation.

  9. End-to-end verification. Walk every user action from the L1 inventory through the new stack on develop-1.0.0 and confirm parity with the current prod behavior before cutover.

Notes​

  • No new design decisions in implementation. If a workflow or endpoint needs to change shape during the build, update the design doc in the same PR as the code. Drift between doc and code is the failure mode this stage was built to prevent.
  • Cutover is a separate event. Tasks 1–9 land on develop-1.0.0. The production cutover (DB migration + DNS flip) is its own short window, planned once Task 9 passes.