A solo build across three tracks. A foundation phase that gated everything. An ADR ledger. A sub-project cadence — brainstorm → spec → plan → build → review — with a Devil's-Advocate pass on every PR. Mobile is through SB18; the backoffice is live behind Clerk auth.
A solo build across three tracks. Mobile sub-projects are mostly sequential; the backoffice opened after the cloud + privacy boundary landed. Track ownership is one person — Nick — throughout.
The internal ops console at admin.thenudgey.com gates every /admin/* route behind Clerk auth — separate dev and prod instances, roles via publicMetadata.role (owner / ops / engineering / readonly). It carries sender + merchant triage, the template editor, DSAR processing, feature flags, and the analytics/ops dashboard. An authenticated Lighthouse + axe-a11y suite runs as a CI gate on every PR (all six admin routes score ≥ 0.9). The mobile app does not use Clerk — it stays on Firebase phone auth.
S∞1 · End-to-end dogfood + bug bash (the on-device "amazed by day 3–5" test on a real line). S∞2 · Play Store internal track release + ODPC sign-off. The SMS (READ_SMS) permission is the hard approval gate, so V1 submits SMS-only first; background location lands as a post-approval update, and thenudgey.com direct-download is the rejection hedge.
S0 is documentation and configuration only. No application code. It establishes the conventions, ADRs, and codegen so every downstream sub-project reads the same source of truth.
Root + mobile + apps/marketing + apps/backoffice. Each ≤800 lines. Tells a Claude Code session in that area what conventions and constraints apply.
Stack · privacy boundary · monorepo+Vercel · Firestore region · AI roadmap · conversation memory · generative discipline · installed-apps · institution taxonomy · ODPC registration · brand-token codegen.
TS source of truth → generated Dart for Flutter. Husky pre-commit + CI both enforce. Drift becomes structurally impossible.
Typecheck + lint + format + token-sync + test on every PR. CODEOWNERS. PR template carries the DA review checklist.
pnpm install succeeds with no errors; warnings reviewed.pnpm typecheck · lint · format --check · test all pass.pnpm gen:tokens produces no diff against committed Dart files.nudgey-dev only.docs/s0-smoke opens, all CI status checks green, merged with at least one review approval.Each lives in docs/decisions/NNNN-slug.md with required sections: Status, Context, Decision, Consequences, Alternatives Considered. The foundation set below is ADR-0001 through 0011; later decisions (e.g. ADR-0017, at-rest DB encryption) were written as their sub-projects landed.
Flutter + Riverpod + Drift on mobile · Next.js 16 + Tailwind on web · Firebase (Auth + Firestore + FCM + Crashlytics + Remote Config) · pnpm + Turbo monorepo.
acceptedLocal-only types lint-blocked from RemoteRepository. Single anonymize() is the audit point. The type system carries the privacy claim, not promises.
Two repos collapsed to one. Apps deploy to Vercel (matches Sweeton's apps layer, free tier covers V1, simpler Next.js DX). DNS at Cloudflare (existing Nick account, at-cost pricing). Names what was overridden vs the playbook.
acceptedConfirmed at Firebase project creation. africa-south1 if GA for all required services, else eur3 for V1 with documented migration plan.
Two cloud LLM use cases ship in V1, both via LlmGateway: Talk to Nudgey (5 turns/day free, 30-day full trial) and the period-story narrative (premium only). On-device extraction is a separate engine (LiteRT-LM). V1.5: swap NudgeGenerator to LlmNudgeGenerator. V2: ML for clustering + anomaly detection. Orchestration is the moat.
Chat history + parsed intent tokens stored locally only. Cloud LLM calls stateless. Optional encrypted cloud backup keyed to user passphrase (not auto-sync).
acceptedV1 commits to agentic Levels 0–3. Levels 4–5 forbidden in V1 and V1.5. Brand consistency, accessibility, predictability are protected values.
acceptedAndroid <queries> element only — never QUERY_ALL_PACKAGES. Registry is a fixed KnownFinanceApp enum. List stays on-device; only aggregate telemetry leaves. iOS does not get this.
Replaces hardcoded 5-bank parser with registry-driven model. Sender-ID-first resolution, heuristic fallback, ops-triage long tail. Six categories. Three V1 coverage tiers.
acceptedTracking ID + filing date for Kenya's Data Protection Act. Annual renewal. Riverbank Solutions Ltd (Kenya) — operating company behind the Nudgey trade name — as Data Controller; backoffice ops as Data Processor handlers.
acceptedCatalogue is human source of truth → TS is machine source of truth → Dart is generated and committed → husky/CI enforce no drift. Typography uses catalogue numbers verbatim for Flutter; web ladder in fontSizes is Tailwind-only.
accepted
Since the foundation set: ADR-0017 (on-device DB at-rest encryption posture) is accepted — presence-gating / dual-master-key rejected, StrongBox + TEE + Android FBE adopted with an accepted rooted-live-device residual. Backoffice auth resolved to Clerk (dev + prod instances, roles via publicMetadata). The on-device extraction LLM migrated to LiteRT-LM (Gemma 3 1B int4) off the deprecated MediaPipe runtime. Still open as sub-project decisions: V2 bank API, africa-south1 migration, iOS launch criteria.
The playbook (docs/Nudgey_Claude_Code_Playbook_v1.1.docx) defined the original 14-prompt build sequence. Each prompt became a sub-project with its own brainstorm → spec → plan → implementation cycle, plus a Devil's-Advocate review before merge. The sequence has since extended past it — SB13 financial detail, SB14 savings ledger, SB15 bill radar, SB16 recovery, and SB18 the Money Map are follow-on sub-projects that kept the same cadence.
| # | Prompt | Maps to | Track |
|---|---|---|---|
| 01 | Foundation | S0 | FOUNDATION |
| 02 | Scaffold + theme system | SB1 | MOBILE |
| 03 | Local data layer (Drift) | SB2 | MOBILE |
| 04 | Cloud + privacy boundary | SB3 | MOBILE |
| 05 | On-device intake + parsers + institution taxonomy | SB4 (expanded) | MOBILE |
| 06 | Pattern engine | SB5 | MOBILE |
| — | Insights engine | SB6 · added in S0 | MOBILE |
| 07 | Voice layer (category-aware) | SB7 | MOBILE |
| — | Talk to Nudgey (cloud chat) | SB8 · added in S0 | MOBILE |
| 08 | Onboarding + Reveal (expanded) | SB9 | MOBILE |
| 09 | Daily-use screens + journeys | SB10 (expanded) | MOBILE |
| 10 | Periodic screens + Sunday Drop | SB11 (expanded) | MOBILE |
| 11 | Polish + ship-ready | SB12 | MOBILE |
| 12 | Backoffice scaffold + RBAC | SC1 | BACKOFFICE |
| 13 | Core admin screens (with sender-triage) | SC2 | BACKOFFICE |
| 14 | Analytics + operations dashboard | SC3 | BACKOFFICE |
| SA | Marketing landing + waitlist | SA · separate | MARKETING |
Fresh Claude Code session, no prior context. Reviews the spec or the merged implementation. Findings save to docs/da-reviews/PROMPT-{n}-{branch}.md. Severity ladder: Blocker · Serious · Minor · Nit.
Brainstorm the sub-project with the user. Decisions captured.
Write the design spec. Then the implementation plan.
Implement on a feature branch. PR opened against main.
Fresh-session review. Blockers + Serious must be fixed or formally waived. Then merge.
Cannot ship as-is. Must be fixed before merge.
Significant risk. Must be fixed or formally waived with rationale.
Worth noting. Can be deferred to a follow-up.
Stylistic / preference. Optional fix.
docs/da-reviews/PROMPT-S0-design.md.docs/da-reviews/PROMPT-S0-build.md.main is protected. Every sub-project lives on a feature branch named <track>/<sub>-<slug>.
mobile/SB1-scaffold-theme
marketing/SA-landing
backoffice/SC1-rbac
Conventional Commits — feat: · fix: · chore: · docs: · refactor: · test:. Scope encouraged.
feat(mobile): introduce SmsSource interface
fix(SB2-da-blocker-1): money is int cents
Markdown, numbered sequentially in docs/decisions/NNNN-slug.md. Required sections: Status, Context, Decision, Consequences, Alternatives Considered.
One-way: catalogue → TS → generated Dart (committed). Husky pre-commit regenerates on staged brand changes. CI re-runs and fails on diff. Drift structurally impossible.
Each area has its own CLAUDE.md (root + mobile + marketing + backoffice). A session reads root + the per-area file for its working scope. Hard cap ≤800 lines per file.
Tests run · DA review link · voice check · privacy boundary check · brand-token sync check · linked spec reference. Lives in .github/PULL_REQUEST_TEMPLATE.md.