Skip to content

HACKATHON_BRIEF.md

Latest commit

 

History

History
115 lines (73 loc) · 5.48 KB

HACKATHON_BRIEF.md

File metadata and controls

115 lines (73 loc) · 5.48 KB
Raw

QuickCrate hackathon brief

This is the filled project brief requested by hackathon-master-playbook-v3.md. It records the product intent behind the shipped v1 scope.

1. One-sentence promise

For evaluators and Android engineers who want to inspect a trustworthy commerce flow without provisioning infrastructure, QuickCrate provides a polished grocery journey that remains interactive, persistent, and repeatable entirely offline.

2. Ten-second demo moment

Add a product and watch the action become the Morphing Crate Bar; then intentionally fail payment, show that the crate is unchanged, retry, and open the one persisted order.

3. Signature mechanic

Morphing Crate Bar — a persistent, accessible bridge from add action to quantity state, item/total summary, and cart navigation. Motion is optional; final state and behavior remain identical when animator scale is zero.

4. Primary user and job

  • Primary audience: hackathon judges, portfolio reviewers, and Android/CMP engineers.
  • Job: understand the product in seconds and evaluate a complete architecture without needing accounts, keys, services, or reliable internet.

5. Category and references

  • Category: Indian quick commerce / grocery delivery.
  • Product references: Blinkit, Zepto, Swiggy Instamart, and bigbasket.
  • Architecture/presentation references: Android-first Compose patterns and Compose Multiplatform guidance.
  • Design-system reference: private Didovia commit 5fdf43505e81150b00acdbcdc347cd3942c39030, patterns only.

See RESEARCH.md for the consolidated findings and prohibited trust failures.

6. Golden path

  1. Launch offline and authenticate with the demo phone/OTP.
  2. Discover or search products and inspect a variant.
  3. Add explicit quantities and open the persistent crate.
  4. Review savings, delivery fee, threshold, and total.
  5. Choose a saved address and mock payment method.
  6. Trigger one deterministic failure and confirm nothing was lost or ordered.
  7. Retry with the same attempt ID and create exactly one order.
  8. Open the immutable order snapshot, profile, and persisted data after restart.

7. Target platform and value hypothesis

  • Current target: Android, where the quick-commerce interaction is native to user expectations.
  • Portfolio value: demonstrate Android/CMP architecture, trustworthy commerce state, accessibility, and offline determinism.
  • Commercial model: intentionally undecided; a formal market/name/legal pass is required before productization.

8. Build platform

Android-first Compose Multiplatform. Android ships now; the product UI, navigation, state, domain, data, Room, and resources are structured as a shared KMP application boundary.

9. Model layer

No AI/model dependency. Product behavior is deterministic domain logic backed by typed fake transport contracts and local persistence.

10. Data

  • Runtime catalog: bundled SeedCatalog with 8 categories, 28 products, and 3 banners.
  • Mutable data: Room schema v1.
  • Initial state: one profile, two addresses, and three historical orders seeded once.
  • Artwork/fonts: bundled local resources with license notices.

11. Integrations

None at runtime. Gradle resolves build dependencies during setup; the installed app performs no network I/O.

12. Repository and distribution

  • Host: GitHub, arpitagarwal1301/quickcrate.
  • Default branch: main.
  • Release: annotated v1 tag with a published GitHub Release.
  • App distribution: source/build instructions only; no signed store or release APK is published.

13. Hard scope cuts

No backend/sync, multiple stores/accounts, real OTP/payment, maps/location, tracking, notifications, refunds/support, inventory/admin, coupons, loyalty, ads, recommendations, pagination, analytics, or additional platform target in v1.

14. Demo environment

Preferred: API 36/37 Android emulator in airplane mode. Fallback: visual README, deterministic fixtures, verifyQuickCrate, and the standalone offline scan.

15. Success criteria

  • A clean install completes login-to-order-history offline.
  • State survives recreation/restart where specified.
  • FailOnce preserves checkout data and retry creates one order.
  • Pricing fixtures are exact integer-paise calculations.
  • No network permission/runtime URL/remote asset enters the app.
  • Host tests, lint, assembly, and connected golden journeys pass.

16. Top risks

  1. Broad acceptance scope exceeds the depth of automated coverage; prioritize idempotency, persistence, accessibility, and responsive regression tests.
  2. KMP/AGP/Room/Navigation compatibility can drift; upgrade only with a clean compatibility proof.

17. Reusable assets

QuickCrate design tokens/components, Room/repository seams, typed fake APIs, the Morphing Crate Bar, local artwork generator, verification scripts, and the documentation/session system.

18. Flags

  • Real authentication: no.
  • Real payments: no.
  • Offline/local-first: yes, required.
  • Personal data: fixtures only.

19. Submission requirements

Public repository, visual README, reproducible build, short demo path, local fallback, release notes, no secrets, and a clean verified branch.

20. Ownership focus

  • Agent handles: implementation, focused documentation, checks, evidence, and bounded repository operations when authorized.
  • Human decides: product direction, taste, release scope, repository/publication actions, licensing, and whether QuickCrate remains a demo or becomes a product.
  • Primary concern: preserve a reliable, instantly understandable golden path while improving proof rather than adding breadth.