arch-atlas

Atlas Demo

Fictional showcase project — the documentation template every real client project starts from.

Flutter · GetIt · GetX · Clean Architecture

Client

Atlas Retail (fictional)

product@atlasretail.example

Environments

  • devapi.dev.atlasdemo.example
  • stagingapi.staging.atlasdemo.example
  • prodapi.atlasdemo.example

Links

API · 5 endpointschanged · 1in progress · 1implemented · 1verified · 2⚠ backend contract changed — see catalogopen catalog →
Atlas Demo
1 feature
1
AuthenticationLogin, register, logout and password reset — the reference feature.
◐ in progress

Delivery Phases

  1. Phase 1 — Foundations & Auth

    signed off3/3

    4 May 2026 → 29 May 2026

    • Design system + theming (light/dark)
    • Auth flows: login, register, logout, reset
    • CI pipeline with signed test builds

    Client signed off 2026-05-29 after UAT on staging.

  2. Phase 2 — Catalog & Cart

    active2/4

    1 Jun 2026 → 24 Jul 2026

    • Product catalog with search + filters
    • Local-first cart
    • Token-refresh hardening (contract change fix)
    • Deep-link handling for password reset

  3. Phase 3 — Checkout & Launch

    planned0/3

    27 Jul 2026 → 4 Sept 2026

    • Checkout with Stripe PaymentSheet
    • Push notifications
    • Store listings + release

Decisions

  • Single-flight token refresh behind a mutex

    18 Jun 2026

    The Dio interceptor serializes refresh calls behind a mutex; concurrent 401s await the same rotation future.

    ›context & consequences

    Two parallel 401s (e.g. home + notifications fetch on boot) each triggered a refresh, and the second rotation invalidated the first token.

    Consequences: Boot-time races disappeared. The 2026-07-10 backend contract change (refreshToken rename) touches exactly one file.

  • Password reset always shows a neutral confirmation

    20 May 2026

    Backend returns 200 for every reset request; the UI shows 'If an account exists, an email was sent' in all cases.

    ›context

    Distinguishing 'unknown email' from 'reset sent' enables account-enumeration attacks.

  • GetIt owns construction, GetX owns lifecycle

    12 May 2026

    Register data sources, repositories and use cases in GetIt; controllers live only in GetX bindings and receive dependencies via sl().

    ›context & consequences

    Controllers need GetX lifecycle hooks (onInit/onClose), but repositories and use cases should be framework-free and testable.

    Consequences: Tests override GetIt registrations with mocks; no controller ever appears in the service locator.