# Vision and scope — what the rebuild is

**One sentence:** rebuild `work` as the operations platform that runs
Bowden Works — and eventually PlusROI, Heather's business, and Summer's
business — covering project management, time tracking, invoicing,
profit sharing, commissions, and bookkeeping, on the server's standard
stack, behind BW Auth, modeled on parties and engagements instead of a
single-org role table.

Source of intent: rian, 2026-07-06 (this session), plus the business
blueprint in `docs/domain/` and everything learned across ADRs
#001–#044.

## Why rebuild instead of evolve

- The **domain model ceiling**: the current schema hardwires one org,
  one role enum, and a two-agency operator concept. The real business
  is a graph of parties with typed, per-project, time-varying
  relationships (see 02-domain-model.md). Retrofitting that under a
  live Supabase/RLS app would be a bigger, riskier project than a
  clean rebuild with a data migration.
- The **server converged on different infrastructure** after this app
  was built: one standard stack (React SPA + FastAPI + Postgres), one
  auth system (id-auth Pattern B — work is already scheduled as a
  Wave 3 migration), self-hosted data. See 03-stack-decision.md.
- The **UX debt is structural**: inline styles everywhere, no design
  system, server round-trip per filter change. "Significantly faster
  loading, easier to navigate, beautiful / fun to use" is a rebuild-
  grade requirement, not a polish pass.

## What stays true (non-negotiables)

1. **Nothing the current app does is lost at cutover** unless
   explicitly phased out (list below). The parity bar is the feature
   specs in 01-current-system/features/ — every behavior there is
   either in the new app or on the phase-out list.
2. **The money invariants hold**: locked-at-write stamps, invoice
   locks, explicit re-stamps (02-domain-model.md §5).
3. **The docs discipline carries over**: features/, decisions.md,
   tests-catalog, UNDOCUMENTED debt log — from day one.
4. **The current app keeps running untouched until cutover.** The
   rebuild is a new project; migration is rehearsable and reversible
   (05-migration-plan.md).

## Phase-outs (confirmed + proposed)

| feature | status |
|---|---|
| Toggl export (/transfer page, lib/toggl.ts, bulkMark/UnmarkTransferred, `transferred_at`) | **Confirmed by rian 2026-07-06** ("I no longer have any need for toggl"). Already ADR #038's direction; the page only survived for a final CSV backup. Rebuild drops it entirely. |
| Toggl CSV *import* path (source='toggl') | Proposed drop: historical Toggl-imported rows migrate as data; the import pipeline supports Clockify + manual only. |
| `rate_proportion` / converted-hours machinery | Already eliminated from the pipeline (ADR #034, task in progress); rebuild never implements it. Historical converted values migrate as archived columns if the diff harness needs them, else dropped. |
| Supabase (auth, RLS, hosted PG, PostgREST RPCs) | Replaced wholesale (03-stack-decision.md). |
| View-as JWT minting (ADR #043) | Replaced by app-layer impersonation — same UX, no cryptographic machinery. |
| Denormalized operator/client/project text columns on entries | Display-cache **role** dropped — FK-resolved display for all resolved rows. The columns themselves carry as immutable `raw_*` import payload (sole identity for unassigned rows; 02-domain-model.md §3). |
| demoing-era password login (`showmethesite`-adjacent flows, must_change_password) | Replaced by id-auth accounts (`account_required:true`). |

## Roadmap shape (each phase independently shippable)

- **R0/R1 — see 09-build-plan.md** for the milestone ladder (M0–M9:
  walking skeleton → Sign in with BW (Pattern B SHIPPED 2026-07-07,
  integrated in week one) → schema + nightly-rehearsed migration →
  read-only mirror over real data → imports → editing + bulk safety →
  invoices → CC/comments/team → hardening + saved views → replay
  month + cutover). The diff harness splits: old-side extractor in
  M0; new-side emitter grows per milestone as the acceptance
  mechanism. ~30–45 sessions + one calendar month.
- **R2 — Engagement visibility + multi-tenant foundations**
  (rescoped per the plan critique — every phase must ship something
  usable): visibility levels enforced and demonstrated on Bowden
  Works' REAL engagements (Adi's subcontractor scope, view-as
  verification), the permission debug view, and the two cross-tenant
  designs R3 depends on: engagement-chain authz traversal (Adi sees
  PlusROI-tenant projects through Adi→BW→PlusROI — judgment #30) and
  the one-transaction-two-ledgers rule (cross-tenant documents are
  ONE row owned by the issuing tenant; counterparty views derive
  from to_party). PlusROI *onboarding* moves to R3, where its data
  is first consumed.
- **R3 — PlusROI onboarding + port the live Airtable system.**
  PlusROI becomes tenant #2 (registries migrate from the bookkeeping
  sheet per 08); worker payables REUSE invoices+invoice_lines
  (from/to_party makes them symmetric — no parallel payables
  structure); **files/attachments + notifications land here** (both
  load-bearing for the SOP being ported: assignment notes, report
  recipients, notify-the-PM steps — storage decision (volume +
  attachments table) and the backup-regime extension happen at the
  START of R3). The
  "Production" base already runs rian's target model
  (08-current-tooling.md §8): sets (YY.MM, recurring autocreation,
  per-set percentage overrides, unit budgets at $5/unit, resourcing
  state machine), assignments (11-state workflow, units, priorities,
  duty-task flags), Client Owner + Project Lead as per-project roles
  with auto-created duty assignments, the Company→Project→Set
  defaults cascade, worker invoicing by attaching assignments
  (Pending/Sent/Paid payables), time-to-task attachment, and
  **prepaid support blocks as first-class objects** (purchase +
  drawdown + balance — replacing the sentinel baseline-entry
  convention). R3's diff-harness equivalent: reproduce the Airtable
  base's live unit budgets and worker-invoice totals from migrated
  data.
- **R4 — Money engine.** Invoice generation from project billing
  frequencies + milestone schedules; the twice-monthly billing runs
  with review workflow and last-month diff check; transaction fees +
  after-fees amounts; per-invoice commissions; realized-FX handling;
  the monthly BW↔PlusROI settlement (revenue − expenses − 3%
  bookkeeping, ÷2 — the formula is now specified from the live sheet,
  08-current-tooling.md §4); paid-by-either-partner expense netting;
  bookkeeping exports. **The acceptance test: retire the
  bookkeeping Google Sheet by reproducing its settlement to the
  cent.** Gets its own design doc when R2/R3 real-world usage has
  sharpened requirements.
- **R5 — External tenants + portals.** Summer's agency (and peers)
  as self-serve tenants; client logins ("see progress on their
  tasks") and commission-partner logins (see their entitlements) —
  every party seeing the system from its own engagement's
  perspective (02 §2 visibility levels). Depends on the id-auth
  invite flow (judgment call #18). Named hardening gates: per-tenant
  admin boundaries incl. the cross-tenant super-admin policy (does
  the operator read a paying tenant's ledger? — decided HERE, not
  discovered by the first external tenant), tenant data-isolation
  audit, portal-scoped capabilities, per-tenant rate limits.

The user-visible promise of R1: same capabilities, dramatically faster
and nicer, one login (SSO), and a foundation where "add Heather's
business" is configuration + data, not a schema rewrite.

## Success criteria

- R1 cutover: diff harness green (invoice totals, monthly summaries,
  per-project aggregates identical); all ported tests green (the
  current 116 + ports of the RPC/permission semantics); one full
  month closed in the new system matching the old.
- Performance: interactive navigation (no full-page reloads), <1s
  cold dashboard on the LAN, instant filter changes.
- Standards: `srv-gw security-audit` clean; version visible in UI;
  zero inline styles; no hand-written API types.