The Path — Read in This Order
Vidar — Master of Craft
The sections below are ordered by conceptual dependency. Each one assumes the previous. A reader who has never seen this codebase and follows the path will arrive at the end with a complete mental model — not a list of facts, but an understanding of how the pieces connect.
1 — The Ledger
Start here. Before infrastructure, before mobile, before AI: what does Casaconomy actually do?
Casaconomy is a personal finance ledger. Profiles are the financial identities it tracks. Groups organise spending across people and purposes. Rules categorise transactions automatically. Shared receipts pass invoices between group members. Licensing determines what features each user can access.
This section answers the question: what problem does this app solve?
→ Features: The Ledger
2 — Security Foundation
Every transaction is encrypted. Here is how.
Before syncing a single byte across devices, Casaconomy wraps all data in an AEAD cipher keyed with an Ed25519 key pair, stored in the OS keychain. The security model is local-first: the server never sees plaintext.
This section answers: why can you trust the app with your financial data?
→ Features: Security Foundation
3 — Your Devices
The vault travels with you.
With the security model in place, the next problem is: how does your data follow you to a second device? This section traces the full arc — from the earliest encrypted-snapshot mechanism, through the Cloudflare sync relay, to the invite-code pairing system, to same-user sync (your phone is your vault), and finally to the device identity and cross-device discovery infrastructure that makes it seamless.
Read this section in order. Each chapter adds one layer on top of the previous.
→ Features: Your Devices
4 — Mobile
Casaconomy in your pocket.
With sync in place, the mobile app arrives. This section covers the iOS/Android port, the onboarding flow for multi-person households, the mobile-first UI work (transaction cards, settings cards, FAB, safe area), and the rule-testing surface that makes the app as powerful on mobile as on desktop.
→ Features: Mobile
5 — Providers
Getting financial data into the ledger.
A ledger is only as good as the data it receives. Providers are the connectors — bank feeds, import pipelines, data sources. This section covers the declarative Cloudflare-hosted plugin model (update providers over-the-air without an App Store release) and the fake-provider harness used to test them.
→ Features: Providers
6 — AI Features
The AI layer, from infrastructure to product.
The AI features depend on a specific piece of infrastructure: a Cloudflare tunnel that bridges the mobile app to the regent’s local Claude CLI, so AI responses draw from the regent’s Claude Max subscription rather than per-request API credits. This section starts with that tunnel, traces the security fix that put the Worker properly in the request path, then follows the AI product features — the local CLI provider, Astrid’s bug-report chat, her project awareness and vision upgrades, the multi-turn fix, and her role as a UX advisor on every UI pull request.
→ Features: AI Features
7 — The Feedback Loop
How the app tells us what’s wrong, from button to GitHub issue.
This is the longest section, and intentionally so. The bug-report pipeline is a first-class product feature: it turns a frustrating moment (something broke) into a structured, AI-assisted report that lands in Paperclip automatically. The section traces the pipeline from the floating report button, through screenshot capture and annotation, sanitisation and R2 hosting, CloudBridge routing on iOS and desktop, URL unification, payload limits, conversation copying, copiable errors, auto-labelling, and finally the integration test gate that verifies the whole path.
→ Features: The Feedback Loop
8 — Quality Engineering
The structural guardrails that make fast shipping safe.
This section documents the engineering process layer: the ESLint and Clippy guardrails wired into CI, the skill-level boundary rules that catch cross-process bugs, the plugin-symmetry check, the acceptance-criteria gate (no implementation without a written AC), the two-action smoke gate for stateful surfaces, and the quality arc that ties them together.
These are not testing chapters. They are process chapters. They answer: what structural pressure keeps the codebase honest?
→ Features: Quality Engineering
9 — UX System
The design authority and how it is enforced.
A consistent UI requires a citable authority. This section covers the UX/UI guidelines living spec, how those guidelines are wired into every audit and review skill, the UX walk that auto-fires on every UI pull request, and Eivind’s autonomous UX walk skill.
→ Features: UX System
10 — Testing Infrastructure
How we verify what we build.
With guardrails and UX authority in place, the verification layer: Storybook with Loki visual regression, test-runner interaction tests, and axe-core accessibility checks; Playwright route-level visual sanity and mobile safe-area emulation.
→ Features: Testing Infrastructure
Appendix — Distribution & Operations
Reference material. Read when you need it, not on first pass.
TestFlight distribution, Cargo disk budget, the main-clone filesystem lock, Paperclip API launchd self-heal, routine residue remediation, shared node_modules and sccache across worktrees, Paperclip version pinning, and the removal of the GitHub Project board integration.
These chapters are operational records, not conceptual building blocks. They belong in the Book for completeness, but they do not advance the reading arc.
→ Features: Appendix
Recap
- The arc runs: ledger → security → sync → mobile → providers → AI → feedback → quality → UX → testing → ops.
- Each section assumes the previous. Security before sync. Sync before mobile. Mobile before AI bridge.
- The Appendix is reference, not narrative. Skip it on first read.