Clearline is a corporate spend platform in the style of Ramp and Brex. It's not happy-path CRUD: it models idempotent payments, separation of duties, role-based access, KYB onboarding, and bank-feed reconciliation — the places where real money software breaks — and surfaces those failure modes honestly in the UI.
Three personas (Employee, Finance Manager, Controller) see different navigation and different permissions, all derived from one permission predicate — never a role string.
One validation gate (balance, daily limit, self-transfer, recipient status), an
Idempotency-Key per intent, 30s timeout, and full-jitter retry on 5xx.
3DS step-up for high-value payments; holds, reversals, and unknown-status handling.
Separation of duties, limit-based escalation, stale-action reconciliation, and partial-failure batch approve/reject with per-item keys and mid-batch resume.
Issuance with limits and MCC restrictions, a real-time WebSocket transaction feed, freeze controls, and security-gated declines.
Exact + fuzzy matching with a similarity breakdown, an actionable exceptions queue, exact-sum split matching, and a Fatal-tier guard that withholds a balance that doesn't net.
Spend by category, department, and vendor with anomaly flags and AI-confidence labels; per-section error boundaries with scoped retry; budget gauges with 80%-warning and over-budget states and period rollover.
KYB onboarding, sign-up and sessions, 2FA, an append-only Controller-only audit log (opening it is itself audited), a full settings surface with re-auth-gated ownership transfer, and role-based getting-started checklists driven by real domain events.
An Nx + pnpm monorepo with one rule of thumb: if it's an invariant it lives in
domain; if it touches the network it lives in data-access; if
it renders it lives in ui or the app.
RequireAuth, RequirePermission…), permission-driven nav.
Renders typed errors; decides nothing.
/api/*.
Mints idempotency keys, applies timeouts and retry/backoff, surfaces 4xx as typed
errors.
--cl-* theme) · icons · money (minor-unit math) ·
contracts (shared API types) · demo-beacon
| Concern | Choice | Why |
|---|---|---|
| Framework / build | React 19 + Vite 7 | Web-only SPA behind auth; no SEO need, so no SSR complexity. |
| Language | TypeScript 6 (strict) | Shared contract types across UI, data-access, and mock backend. |
| Routing | react-router 7 | Nested layout routes carry the guard chain; version pinned below the 8.x major on purpose. |
| Server state | TanStack Query 5 | Cache, retry, and mutation lifecycles instead of hand-rolled effects. |
| Forms | react-hook-form + Zod | Schema-validated input with errors tied to fields for accessibility. |
| Styling | Tailwind v4 + Radix |
Tokens in @theme, light/dark; accessible primitives underneath.
|
| Mock backend | MSW v2 | Same handlers run in the browser demo and in tests. |
| Testing | Vitest · Testing Library · Playwright | Domain unit tests, component tests, and role-based e2e flows. |
| Design system | Storybook 10 + Chromatic | Every component ships stories and docs; visual regression in CI. |
| Tooling / CI | Nx 23 · pnpm · GitHub Actions · Husky · commitlint | Affected-only builds and tests; conventional commits tied to story IDs. |
| Hosting | Vercel | Git-driven previews; CI verifies, Vercel deploys. |
The choices that shaped the codebase, and why I made them.
validatePayment, retry policy, match classifier, and auth rules are
framework-free TypeScript.
Idempotency-Key; 5xx retries use
full-jitter backoff; batches use per-item keys.
@clearline/money lib owns currency conversion; budget
percentages and overages are computed on integers.
VITE_ENABLE_MOCKS.
I set the architecture, make every technical and product decision, and built the development system that three AI tools work inside. Nothing moves from one stage to the next until I have read the actual text and said yes. It's the process a good product team runs — written specs, recorded decisions, tests first, code review, and a check on the real screen — defined in the repo and directed the way a tech lead directs a team.
specs/), a numbered record for each technical decision, and a fixed cycle
every feature goes through.
Each tool has one job and one thing it is never allowed to do. The tool that writes the code is not the one that judges it.
| Who | Role | Does | Never |
|---|---|---|---|
| Me | Architect, tech lead, product owner | Set architecture and constraints, design the workflow and its rules, make every engineering decision, review specs and code, test on the real screen, merge | Approve a summary instead of the actual text |
| Claude Desktop | Reviewer & planner | Reads reports against the specs and decision records, recommends a ruling, drafts the next prompt, runs the design work | Touches the repository |
| Claude Code | Executor | Runs the repo's commands to write specs, tests, code, commits and pull requests; uses subagents for review, deviation audits and context loading | Continues past an approval gate on its own |
| Claude Design | Designer | Holds the design system and draws every screen state on a design canvas | Invents a state no story asks for, or adds a token without approval |
A typical exchange: Claude Code stops at a gate and reports what it did, found, and needs decided. I paste that report into Claude Desktop, which checks it against the records and returns one recommendation and one complete prompt. I approve, change or reject it, and paste it back. One prompt at a time, because the first result changes what the second should say. Prompts stay short because the procedure lives in the repo's own commands, versioned with the code.
Every feature follows the same path from idea to merged code. Each step is a command in the repo, so the process is identical in every session.
What the app should do, why now, what's out of scope, what done looks like. Open product questions are settled first.
/spec-feature turns the brief into an epic and user stories with
acceptance criteria, all draft. /validate-registry checks structure.
I read the full acceptance criteria and run /approve-epic myself. The
build command checks for approval and stops without it.
Claude Design draws every state the stories imply.
/validate-design-export checks it against the design system.
/load-spec-context gathers the epic, stories, decisions and designs
once, so every session starts from the same picture.
/reconcile-decisions finds every earlier decision that applies and
says whether this work follows, amends or replaces it.
/assess-tradeoffs lays out any real engineering choice with its
consequences. I decide; the decision is written down.
/implement-feature works one story at a time, test first — each test
must fail for the right reason before any code exists.
/apply-design translates designs into components, listing every
state first.
I test the built functionality in a real browser against the design, state by state.
/review-code checks the change against the project's binding rules
and quotes any rule it breaks.
/review-deviations compares what was built with what was specified
across the whole epic.
/create-pull-request writes the description, including manual test
steps and any declared deviations.
I merge. Stories are marked implemented only if every criterion is met.
/explain-implementation writes up how the feature works and what was
learned while it's fresh.
Small fixes skip most of this. Anything touching money, permissions or personal data gets the full cycle whatever its size.
A design system holds tokens, icons, component guidelines and contrast documentation. The repo holds a read-only copy, updated only by syncing from the source and never edited by hand. Code reads only that copy.
Every state gets its own artboard: empty, loading, error, offline, light and dark. Every visual value is a token; new tokens are approved into the system as a separate step.
There's no designer to leave questions for, so every product and data question is settled before the brief is written. An open question produces invented scope.
If the app and the design differ, the difference goes in a hand-kept log. Nobody edits a design file to make it match. After merge, approved artboards replace the library's.
Written in the repo's CLAUDE.md as binding constraints. Review commands
check work against them and quote the rule that was broken.
When a gate or review catches a defect, the fix isn't only the code — I change the rule and record why, so the same failure costs less next time.
Output quality followed the quality of the spec, the decision history and the rules file, not how cleverly I worded a prompt.
The session that wrote the code carries its own assumptions about what it built. A separate session doesn't, so it checks the work against the spec and the rules instead, and catches gaps the builder can't see.
Reviewing the acceptance criteria before the build takes minutes. Fixing a misunderstanding after the code is written means rework.
Commands, templates and rules are versioned and reviewed like code, so the process improves with each change and survives every new session.
Epics and user stories live in the repo as versioned files, not in a separate tool. The assistant reads the same requirements I do in every session, a change to a requirement goes through review like any code change, and each commit traces back to a story.
A registry that says "implemented" about partial work is confidently wrong, and every later decision inherits the error.
Try the flows, then read the code. The domain libraries and their tests are the best place to start.