docs: rewrite README for the YouCam hackathon and refresh ARCHITECTURE

[jvsena42]

Summary

Both top-level docs had drifted far behind the code. The README still described the app as it stood ~200 commits ago — four bullet points, no mention of the YouCam Apparel VTO integration, outfits, gaps, on-device AI, background removal, or share-sheet entry. ARCHITECTURE.md was equally stale: the module tree said androidApp/, the code samples predated Result<T> and constructor-injected dispatchers, and the AI section covered only the Claude API.

Worn is being submitted to a hackathon judged on integration of a Perfect Corp. YouCam API, so the README is reframed submission-first: a judge should understand the problem, see the try-on working, and grasp the depth of the integration within 30 seconds of scrolling. Developer docs move below the fold. ARCHITECTURE.md becomes an accurate technical reference for the same judge who clicks through.

Docs and assets only — no code changes.

Changes

README.md (rewritten)

• Problem statement grounded in design/Persona.md: two unknowns at the moment of purchase — does it look good on me and does it work with what I already own — and every shopping tool answers at most one.
• Demo section embedding screenshots/try_on.mp4, with a plain markdown link as fallback.
• Screenshot gallery: 3+2 table of the five new PNGs with captions.
• Feature sections led by Try It. The "this isn't a wrapper around one API call" argument is carried in the descriptions rather than a separate pitch block: the try-on is gated behind a real catalogued wardrobe, so the render arrives next to a buy/skip verdict grounded in what you own, and share-sheet + launcher-shortcut entry put it in the store rather than only in the app.
• How the YouCam integration works: the five-step S2S flow, RSA id_token auth (with the SPKI-vs-PKCS#1 expect/actual split called out as the KMP-interesting part), category-routed cloth-v3/shoes endpoints, polling, and error mapping — plus a table linking the relevant files.
• BYOK setup table, including the two YouCam portal gotchas the code already surfaces (shorter value is the client_id; paste the secret without the PEM header lines).
• Privacy section: app-private photo storage, Keystore/Keychain secrets, HTTPS only.
• Tech stack table corrected against gradle/libs.versions.toml and extended with Coil, DataStore, ML Kit, Turbine/MockK, and Detekt; project structure updated to the real layout.
• Lightning tip section kept verbatim.

ARCHITECTURE.md (refreshed, structure preserved)

• Module tree: androidApp/ → composeApp/; adds data/source/{ai,image}, util/{image,crypto}, commonMain/sqldelight/, androidHostTest/, journeys/.
• Real repository signatures — Result<T> for one-shot reads, Flow<T> for reactive ones — plus TryOnRepository and the name-keyed SecretStore.
• Data-layer samples updated to current conventions: constructor-injected CoroutineContext, and runCatching as the outer wrapper around withContext.
• §5 split into Claude API / on-device AI / YouCam Apparel VTO.
• Security table gains the YouCam credential rows; testing section replaced with the real commonTest + androidHostTest layout, ktor-client-mock, and journeys/.
• Decision log gains BYOK, injected CoroutineContext, Result-returning repositories, DataStore over SharedPreferences, on-device AI as a swappable provider, and expect/actual RSA.

Assets

• screenshots/ — five PNGs and try_on.mp4 (a recording of an actual YouCam render).

Test plan

• Every file path and link target referenced in the README verified to exist (YouCamApiClient.kt, YouCamApiModels.kt, TryOnRepositoryImpl.kt, RsaEncryptor.kt + both actuals, journeys/README.md, all six screenshot assets).
• Technical claims checked against source rather than taken from the plan. Four drafted claims were wrong and were corrected before commit: there is no single AiSource interface (WardrobeRepositoryImpl holds ClaudeApiClient and OnDeviceAiSource and selects per call); runCatching wraps withContext, not the reverse; BackgroundRemover's actual does dispatch itself; and analyzeProspectiveItem stays on Claude regardless of the on-device preference.
• Tech stack versions cross-checked line by line against gradle/libs.versions.toml.
• ./gradlew detekt passes.
• Reviewer: confirm the try_on.mp4 player renders in the README on github.com. GitHub's handling of <video src> with a repo-relative path is inconsistent; if no player appears, drag the file into a draft issue to get a user-images.githubusercontent.com URL and swap it into the src. The text link below it works either way.

Checklist

• ./gradlew detekt passes
• Tested on Android — n/a, docs-only change
• Tested on iOS — n/a, docs-only change
• Updated documentation (if applicable)

Note

screenshots/try_on.mp4 is 10 MB and git history is effectively permanent, so every future clone pays for it. It is the most persuasive asset in the submission, so it is committed as-is — but reversing that decision after merge means rewriting history. The alternative is hosting the video via a GitHub issue upload and referencing that URL instead. Worth a moment's thought before merging.

🤖 Generated with Claude Code