T
Sign in

PHASES-GUIDE.md — the build phases: meaning + how you check them

All docs GitHub source

PHASES-GUIDE.md — the build phases: meaning + how you check them

Owner-facing guide to the complete-to-spec build program (PLANNING §97, docs/COMPLETION.md). Each phase: what it means in plain words, what it means technically, and exactly how the owner checks it. "Checking" is never reading code — it is the 3-layer contract: automated proof (the suites, shown as green) + a one-page Verification Sheet per phase + your own 5-minute spot-check with a real document.

Every slice must pass the Definition of Done (all six) before it can be called done:

  1. Every field the specs require is present, entered the right way (auto / scan / select / number — no typing on the floor).
  2. The flow works end to end — completing a step creates the next one.
  3. Paper prints match your formats — only at the EXTERNAL boundary (internal steps are taps in the system).
  4. The CSV/Excel download works for that screen.
  5. Works with YOUR real data — numbers make sense, nothing crashes.
  6. All checks stay green; nothing outside the slice was touched.

Then YOU test it with one real document the same day and sign the phase's Verification Sheet. Mismatch → that slice reopens. Nothing is marked done without your signature.

Statuses you will see in docs/COMPLETION.md: pending (not started) · in-progress · done-verified (you signed) · blocked-owner (waiting on a 10-minute decision from you).

Phase 0 — Foundations & invariants (the safety net)

Layman: The invisible rules every screen must obey: every action leaves its mark (like a signed ledger nobody can erase), only logged-in people can do things, and nothing gets silently changed or deleted. This is the spine the whole product stands on.

Technical: Append-only enforcement (the only in-place edits are the audited masters exception, PLANNING §86); every mutation logs an event (evt table) via logEvent/appendAmendment; auth choke points — hooks.server.ts refuses anonymous form POSTs (401 → /signin) and +layout.server.ts gates every route by role (ROLE_PAGES); green baseline: unit suite, type-check, build, deploy.sh loop.

How you check (10 min, done for slice 1 — sign it):

  1. Private/incognito window (logged out) → any work screen bounces you to sign-in.
  2. There is no Edit/Delete anywhere except Masters (audited by design); corrections happen via "Amend" on records.
  3. Create a gatepass → tap it out on the Guard page → its record's Events card now shows the exit event (before this slice, that tap left no trace).
  4. Paper trail: COMPLETION.md (Phase 0 row) + BUILD-LOG rev 47.

Phase 1 — Database complete (the filing cabinet)

Layman: Every file the business keeps (parties, yarns, designs, orders, gatepasses, lots, beams, rolls…) and every field on it is defined exactly per your paperwork — including all the dropdown values (statuses/kinds). The database becomes the single agreement every screen reads from, so no screen can drift from another.

Technical: Full schema audit vs the field specs (FIELDMAP §1); every table/column/status value set formalized; identified gaps land as migration 0009+: warp_shrinkage_pct on design · formal order.status list (open → in-prod → delivered → closed) · formal gatepass.status enum incl. partial/due · roll grade/status alignment (A/B/C/R/+reject, lumps) · bale entity decision; live data.db diffed against the migration series (0000–0008 verified) for push-vs-generate drift; tenancy seams confirmed on all 27 tables; company identity (src/lib/company.ts GSTIN) configured.

How you check (10 min):

  1. Open Party, Yarn, Design records in Masters — every field you'd write on paper is there (party address/GSTIN/PAN, design reed/pick/width/ counts/UTL/HSN/GSM…).
  2. Create one of each with a real example of yours — values save exactly as typed.
  3. Your imported data must be intact (909 contracts · 6,688 beams · 2,048 lots · 468 parties): open a few and confirm nothing changed.
  4. Tell me any field you expected and didn't find — it goes in as a gap.

Phase 2 — Engine & services (the calculator)

Layman: All the math your business runs on — kgs ↔ meters per construction, costing per meter, sizing add-on, job rate, GST — lives in one place and behaves exactly like your costing sheet. Every screen uses the same numbers, so nobody hand-computes.

Technical: yarnMath (kg/1000m = 0.5905/Ne; denier /9000; multi- warp/weft splits; lasa/L2L warp allowance; size add-on; weft waste; margin table 1–20%; per-row GST toggles), tippanSolver (krill × parts), intake capture parser, ops services (document numbering, events, amendments, approvals) — unit-tested against COSTING.md §5 (verified to ~0.002%).

How you check (10 min):

  1. Quote screen: type a construction exactly like one on your costing sheet → the weight ladder (warp/weft/sized/fabric/costing kg per m) and the ₹/m cost lines must match your sheet to ~0.001.
  2. The margin table (1–20%) and GST toggles behave as in your sheet.
  3. Krill solver on a tippan: ends ÷ krill → parts/beams look right.
  4. Procurement suggestion numbers vs your own Excel.

Phase 3 — Shared platform layer (the standard toolset)

Layman: Every list screen gets the same search / filter / sort / download, every record opens with Amend / Approve / Print, mistakes show as clear error messages instead of failing silently, and party/quality pickers type ahead as you type. One consistent way of working everywhere — no more "every screen behaves differently."

Technical: List standard (search/filter/sort/pagination/totals/CSV via /api/dump); record pages with append-only Amend modal, owner-gated Approve, Print only at external boundaries; error banners (fail(400) + page.form?.error, incl. the superforms standard for plain forms); comboboxes for party/design; SmartTable rollout to all list screens.

How you check (10 min):

  1. Pick any list screen (orders, beams, lots, gatepasses): typing searches, column headers sort, filters narrow, rows open their record.
  2. On any entry form, type garbage into a number field → you get a clear error message, never silence.
  3. A record page shows Events + Amendments; Amend opens a note box; Print exists only where goods cross your gate (gatepass, challan, beam card, hishob).
  4. "⬇ CSV" downloads a same-shape file on every list.

Phase 4 — Transactional spine (your daily work, end to end)

Layman: The main line: masters → lead/quote/order → booking → gatepass in → stock → beams/sizing → weaving → checking → dispatch → hishob. Each step creates the next (no dead-ends), statuses move by the work itself, and paper appears only when goods cross your boundary.

Technical: Dependency-ordered vertical slices (each only built after the data feeding it exists), event-driven statuses, next-step creation, role-gated, per-slice Definition of Done (fields · flow · print at external boundary · dump · real data · tests green).

How you check (per slice, 15 min with one real document): Take ONE real document from your desk (a gatepass, a beam card, a checking slip, a dispatch slip) and enter it in the system on your phone end to end: each step's next card appears, the print at the boundary matches your paper format, the CSV download works, and your imported numbers stay consistent.

Phase 5 — Read models (the boards)

Layman: Your morning picture: what's pending, what's in stock, what must move today — every number live (never yesterday's batch). Reports become downloaded snapshots of the same live picture, stamped with "as of" time.

Technical: board.ts aggregates + realtime hub (SSE live snapshot), BOARDS-A components per spec (drill tree ending at the form, What·Data· Who comments, period bars, anti-overload), placed reports (R/RL per REPORTS.md) + dump station (DUMPS.md); "runtime, not periodic".

How you check (10 min in the morning):

  1. The dashboard numbers match what is actually in your godown/floor right now.
  2. Click a tile → drill reaches the row → the action/approve/dump is right there (no jumping to a separate Reports menu).
  3. Any export carries an as-of timestamp and filter echo; a report is a finished product — the number you act on, not a spreadsheet to pivot.

Phase 6 — Capture & OCR (the scanner)

Layman: Photograph or forward a handwritten gatepass / hishob slip / rate list and the system reads it and fills the form for you; you just tap to confirm or fix one field. Plus camera scanning for lot/beam/roll QRs — no retyping on the floor.

Technical: /api/ocr (tesseract + preprocessing + PSM retry), per-form field templates (fixed paper boxes → cropped OCR with digit whitelists for handwriting; optional cloud handwriting OCR only if you approve), confirmation screen (field-level confidence → tap-fix → record), camera QR/bar-scan buttons into guard/godown/checking/dispatch, rate-list OCR → /rates.

How you check (needs ~6 sample documents you provide): photograph one of YOUR handwritten gatepasses → fields prefill → confirm. Scan a beam/lot barcode with the phone camera → the record opens. A rate-list photo → today's rates land as drafts.

Phase 7 — External integrations & packaging (the bridges)

Layman: The edges: Tally receives your vouchers, the Android capture app gets built, WhatsApp confirm-links finish, and multi-company readiness is verified.

Technical: BRIDGE file contracts (idempotent import ledger, external_id), Tally voucher export (G1), Trading Capture APK build (needs your signing key), /c/* confirm-link finalization, tenancy enforcement trigger check per PLATFORM.md Stage-2.

How you check: a Tally import file opens cleanly and reconciles · the APK installs on your phone and a WhatsApp forward lands as a draft · an external party taps the confirm-link in the WhatsApp message and the record updates in-system.

Phase 8 — Hardening & cutover (the final proof)

Layman: Every role walks their screens on your real data; security and speed are checked; then ONE switch — the old software goes read-only/archive and this becomes the working system.

Technical: full role-by-role journey run (the live suite), security audit, performance pass on real data, backups, sign-off, single cutover per ARCHITECTURE.md §5 / the one-go guardrail.

How you check: you walk EVERY screen with a real document from your desk; the final sign-off sheet closes the program; the old system stops being the working system.

The four "10-minute decisions" flagged along the way (blocked-owner)

They surface at the phase that needs them — none blocks earlier work: ① your GSTIN for the print header · ② numbering sequences (booking/contract/GP/PS) · ③ bale entity (build vs keep deferred) · ④ party SPOC fields (per-department contacts for WhatsApp).

How to read progress: docs/COMPLETION.md is the one scoreboard — every phase/slice with its status, the findings ledger, and this guide's check steps as the verification contract.