docs: stand up architecture documentation for the Android app #960
Merged
bmc08gt merged 7 commits intoJun 22, 2026
Merged
Conversation
Add a docs/architecture/ suite modeled on the iOS app's architecture docs (code-ios-app e53fe01), tailored to the Android codebase: a README index plus nine numbered topic docs (modules & boundaries, state & DI, navigation, networking, persistence, payments & operations, design system, cross-cutting concerns, separation of concerns) and a representative feature catalog. Each doc opens with an intent statement and a Mermaid diagram. Documents the code as it exists today, correcting three stale CLAUDE.md notes: navigation is Navigation3 + a custom CodeNavigator (no Voyager); the Room DB is not SQLCipher-wrapped but uses a per-user database name derived from account entropy; async is effectively pure Coroutines + Flow (no RxJava). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
The architecture suite used "coordinator" loosely. Add a canonical "Roles" section in 02 (state & DI) defining Coordinator, Controller, Manager, and Service, with the TokenController (stateless network gateway) vs TokenCoordinator (session/lifecycle-aware owner of cached domain state) example drawn from their own KDoc. Point the loose mentions in 01 and 09 at this definition and split the "where does this code go?" guidance into Coordinator (cached/synced domain state) vs Controller (stateless shared logic). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
Add three how-to guides under docs/architecture/ that cover working in the codebase rather than its structure: - 10-build-and-run: prerequisites, the API keys actually consumed (MIXPANEL/BUGSNAG/COINBASE_ONRAMP/GOOGLE_CLOUD_PROJECT_NUMBER) and how tryReadProperty resolves them, Gradle commands, variants, CI. - 11-adding-a-feature: end-to-end walkthrough (module -> ViewModel -> screen -> AppRoute -> appEntryProvider -> shared deps), tying together docs 01/02/03. - 12-testing: what to test where, :libs:test-utils (TestDispatchers, MainCoroutineRule), Robolectric, fakes, and Turbine; links to the existing Compose UI testing guide. Index and reading paths updated to surface the guides. Fix stale claims in CLAUDE.md to match the code: required local.properties keys (FINGERPRINT_API_KEY is not used; COINBASE_ONRAMP_API_KEY is), navigation is Navigation 3 + a custom CodeNavigator (not Voyager), async is Coroutines + Flow (not RxJava), and Room uses a per-user database name from entropy (not SQLCipher). Point CLAUDE.md at docs/architecture/. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
…glossary Fill the remaining documentation gaps for new developers and agents: - 13-protobuf-and-codegen: definitions/* layout, the protobuf/protoc codegen, the "never hand-edit generated models" rule, and the /fetch-protos + proto-change-tracer workflow. - 14-error-handling: Result<T> at the service boundary, per-operation sealed error hierarchies over CodeServerError, NotifiableError (bug vs expected), and retryable/retryableOrThrow. - 15-ci-and-release: the CI check, Fastlane lanes, release workflows, and the build-lookup/r8-mapping/release-notes skills. - 16-agents-and-skills: a task -> tool map for the repo's Claude Code agents and skills. - glossary: domain & architecture vocabulary (USDF, intent, timelock, rendezvous, coordinator, etc.). Index and reading paths updated to surface all of the above. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
USDF is the base reserve currency ("core mint"); launchpad currencies are the
user-facing tradable tokens backed by USDF reserves (like memecoins backed by
USDC). The docs previously framed them as parallel holdings, understating the
backing relationship.
- 06: add a "Currency model" section — USDF (MintMetadata with launchpadMetadata
= null) vs launchpad currencies (non-null LaunchpadMetadata: liquidityPool,
coreMintVault USDF backing, price/marketCap in USDF, sellFeeBps), on-chain
bonding-curve price discovery, buy/sell against USDF via SwapPurpose, and the
two distinct senses of "reserves" (pool backing vs the user's USDF balance).
Adds a reserve/pool/token Mermaid diagram.
- glossary: rewrite USDF, launchpad token, and swap; add core mint, bonding
curve, liquidity pool/coreMintVault, reserves, MintMetadata/Token.
- README: reframe the overview around USDF-as-reserve / launchpad-as-circulating.
- features: align cash, tokens (buy/sell vs USDF), and currency-creator rows.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
These were conflated in the glossary. They are distinct: - Kik Code is the scannable, animated circular code itself — the device-to-device transport. It is surface-agnostic: currently displayed on cash bills, soon on digital gold bars, and could later back other flows such as merchant payments. - Cash bill is a digital representation of "cash" (like a US dollar), modeled as Bill.Cash; it carries a token (launchpad currency or USDF) and displays a Kik Code for the recipient to scan — one of the surfaces the code rides on. Rewrites the two glossary rows and aligns the README overview line and the features scanner row to match. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
CLAUDE.md was corrected earlier on this branch (navigation, persistence encryption, async, API keys), so the notes claiming this suite contradicts "older notes / stale references" no longer apply. Reframe them as plain factual statements: - README: remove the "contradicts older notes in CLAUDE.md" paragraph; keep the "code is authoritative" guidance. - 03/05/08: state the facts (Navigation 3 not Voyager; Room not SQLCipher; Coroutines + Flow, no RxJava) without the "are stale" clauses. Remaining CLAUDE.md references are plain pointers and left as-is. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.