QuickCrate

A complete quick-commerce journey that works without a network.
Discover groceries, build a persistent crate, see every fee, recover a failed payment, and find the order later—all inside an Android-first Compose Multiplatform app.

Android-first · Compose Multiplatform · Navigation 3 · Room 3 · Offline by design

The product in eight screens

QuickCrate is built for the moments that make or break trust in a commerce app: explicit cart changes, transparent totals, failure without lost work, and an order that is created exactly once.

1. Enter locally Demo credentials open a persistent, offline account.	2. Discover Delivery context, search, banners, aisles, and local product art.	3. Decide Variants, current price, original price, and savings stay visible.	4. Build the crate The signature crate control becomes quantity controls and a clear next action.
5. See the math Subtotal, savings, delivery fee, threshold, and payable total.	6. Choose payment UPI, card, and cash are safe mocks; no payment data is collected.	7. Recover safely A deterministic failure retains the crate and exposes an explicit retry.	8. Confirm once Retry creates one persisted order, clears the crate, and opens history.

Screenshots are from the verified API 36 emulator build. Artwork, catalog data, and mutable state are local.

What makes QuickCrate useful

• A complete vertical slice. Login, discovery, search, product variants, cart, addresses, payment, retry, order history, profile, and restart persistence are connected rather than presented as isolated samples.
• Trust is visible in the interface. The cart only changes after an explicit user action. Pricing is calculated in integer paise and shown before checkout. A failed attempt never clears the cart or creates a partial order.
• The demo is repeatable. Bundled data, local artwork, Room persistence, controlled coroutine latency, and a one-shot failure hook make the same journey available in airplane mode.
• The design system is part of the architecture. Semantic color, typography, shapes, spacing, motion, adaptive behavior, and accessible components live in shared code and are consumed by feature screens.

Compose Multiplatform is the application boundary

Many multiplatform samples share models or networking while leaving the product UI platform-specific. QuickCrate deliberately shares the entire screen-to-store path. Android owns the executable shell; the shared KMP module owns the application.

flowchart TB
    subgraph Android[androidApp · Android shell]
        Manifest[Manifest and resources]
        Activity[Application and MainActivity]
        Platform[Android context and reduced-motion seams]
    end

    subgraph Shared[shared · Compose Multiplatform application]
        Theme[Design system and local resources]
        Nav[Serializable Navigation 3 routes]
        Screens[Feature screens]
        State[ViewModels · immutable StateFlow · events]
        Domain[Domain models and pure rules]
        Repos[Repository contracts and implementations]
        APIs[Typed fake APIs · latency · FailOnce]
        Store[Room 3 local store · bundled SQLite]

        Theme --> Screens
        Nav --> Screens
        Screens --> State
        State --> Domain
        State --> Repos
        Repos --> APIs
        Repos --> Store
    end

    Manifest --> Activity
    Activity --> Nav
    Platform --> Store

Loading

The runtime contract stays narrow and replaceable:

Compose screen
    ↕ immutable UI state + one event entry point
ViewModel
    ↓ repository contract
Repository implementation
    ↓ typed fake API + Room/local fixtures
Persistent, deterministic result

This gives QuickCrate a few useful properties:

• Routes carry IDs and enums instead of domain objects.
• Feature composables never call Room or fake APIs directly.
• ViewModels expose immutable StateFlow and narrow navigation/message effects.
• Checkout uses a persisted attempt ID and a Room transaction for idempotence.
• The Android entry module can stay small while shared code remains ready for another host target.
• Manual constructor injection keeps the object graph visible without a DI framework.

Purpose-built demo capabilities

These constraints are features required for a dependable product demo:

• Offline execution: no backend, HTTP client, runtime URL, remote image loader, analytics SDK, or internet permission can influence the run.
• Safe authentication: one local account proves validation and session persistence without sending a phone number or OTP.
• Safe payments: UPI, card, and cash responses are simulations, so the complete checkout can be evaluated without credentials, tokens, or money movement.
• Controlled failure: “Fail next attempt” proves recovery, retained cart data, and idempotent retry on demand.
• Focused catalog: one store, 8 categories, 28 products, 3 banners, 2 addresses, and seeded order history provide enough breadth for the journey without hiding behavior behind pagination or services.
• Local-first assets: original QuickCrate artwork and bundled fonts make every screen available after a cold start in airplane mode.

Explore the demo

Requirements: JDK 17 and Android SDK 37.

./gradlew :androidApp:installDebug

Use the built-in demo identity:

Phone: 9876543210
OTP:   123456

Suggested 90-second path:

1. Use Fill demo credentials and enter QuickCrate.
2. Open a product from Fast favourites, choose a variant, and add it.
3. Open View crate and inspect the complete pricing formula.
4. Continue to payment, enable Fail next attempt, and pay.
5. Confirm that the crate is unchanged, then tap Retry.
6. Open the persisted order and visit Orders or Profile.
7. Force-stop and relaunch to see the session, cart/order, addresses, and profile survive.

For longer walkthroughs, see DEMO_SCRIPT.md.

Project map

androidApp/
  AndroidManifest.xml, Application, MainActivity, launcher resources
  connected UI journeys and persistence tests

shared/
  designsystem/    semantic theme, accessible components, Morphing Crate Bar
  navigation/      serializable Navigation 3 keys and back-stack ownership
  feature/         screens and immutable ViewModel state/event contracts
  domain/          money, catalog, cart, customer, order models and pure rules
  data/api/        typed contracts and deterministic fake implementations
  data/local/      Room database, DAOs, seed coordination, atomic checkout
  data/repository/ repository implementations and manual application graph
  composeResources bundled fonts, catalog data, seed data, and original artwork
  commonTest/      pricing, cart, search, validation, order, and fake-API tests

The deeper route, schema, pricing, and failure semantics are documented in SPEC.md. Product research and trust decisions are in RESEARCH.md.

Technology

• Kotlin and Compose Compiler 2.4.10
• Compose Multiplatform 1.11.1
• Android Gradle Plugin 9.1.0 and Gradle 9.3.1
• Navigation 3 Multiplatform 1.1.1 with serializable route keys
• Multiplatform Lifecycle and ViewModel 2.10.0
• Room 3.0.0 with SQLite bundled driver 2.7.0
• Coroutines and kotlinx.serialization 1.11.0
• Android minSdk 23, targetSdk 36, compileSdk 37

Navigation uses the published Compose Multiplatform Navigation 3 1.1.1 artifact. The planning draft named 1.1.2, but that coordinate was not published when this implementation was verified.

Offline and quality verification

Run the complete local gate:

./gradlew clean verifyQuickCrate
./scripts/verify-offline.sh

Run the connected Android journeys on an emulator or device:

./gradlew :androidApp:connectedDebugAndroidTest

The verified gate covers:

• Host tests for integer pricing, cart operations, search, validation, order creation, and fake failure behavior.
• Android lint and debug APK assembly.
• Four API 36 journeys covering login, seeded orders, payment failure/retry, and activity recreation.
• Room schema v1 export and persistent session/cart/order round trips.
• Manifest inspection with no INTERNET or ACCESS_NETWORK_STATE permission.
• Runtime scans rejecting HTTP(S) URLs, remote-image fields, and missing local artwork.

Continue development

Start a fresh coding session with AGENTS.md and SESSION_START.md. They define the reading order, protected invariants, verification ladder, and copy-paste continuation prompt.

Document	Use it for
HANDOFF.md	Current release/repository state, verification evidence, known gaps, and the single recommended next task
SPEC.md	Product behavior, golden path, pricing, trust, design/accessibility, and scope contract
ARCHITECTURE.md	Actual modules, layers, navigation, persistence, checkout sequence, resources, and extension recipes
ROADMAP.md	Prioritized hardening, public-project work, product direction gates, and owner decisions
TESTING.md	Exact commands, current coverage, device/manual matrix, and gaps that must not be overclaimed
DECISIONS.md	Accepted architecture/toolchain/release choices and their consequences
CONTRIBUTING.md	Change placement, conventions, test requirements, and review checklist
HACKATHON_BRIEF.md	Filled product brief, demo moment, target, cuts, risks, and ownership
DEMO_SCRIPT.md	Preflight, 90-second/3-minute demos, fallback, and Q&A
RESEARCH.md	Competitor-flow synthesis, trust failures, product wedge, and revalidation trigger
PRIVACY.md / SECURITY.md	Local-data behavior, security boundaries, and disclosure process
CHANGELOG.md	Shipped and unreleased user-visible/architecture changes
MOBILE_APP_KICKSTART.md	Reusable idea-to-release template and exact prompts for starting a different Android/CMP mobile product

Historical inputs remain available in .air/plans/quickcrate-android-cmp.plan.md and hackathon-master-playbook-v3.md; they are context, not the current-state handoff.