# Specification: 002-login-auth-flow

## Status

| Field | Value |
|-------|-------|
| **Created** | 2025-12-24 |
| **Current Phase** | PLAN Complete - Ready for Implementation |
| **Last Updated** | 2025-12-24 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | P0 requirements (FR-001 to FR-010) scoped |
| solution-design.md | completed | 8 ADRs confirmed, architecture defined |
| implementation-plan.md | completed | 6 phases, TDD approach, full task breakdown |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2025-12-24 | User-scoped JWT tokens | Single token works for all stores, simplifies mobile app |
| 2025-12-24 | Email/password only (no PIN) | PIN is for kiosk devices, not personal mobile |
| 2025-12-24 | Skip store picker for single-store users | Reduces friction for majority of users |
| 2025-12-24 | Biometric → straight to home | Fastest path for returning users |
| 2025-12-24 | Store switcher in app bar header | Always visible, easy access |
| 2025-12-24 | Clock-in on home screen only if in geofence | Prevents invalid clock-ins |
| 2025-12-24 | Background location monitoring | Enables smart store detection + notifications |
| 2025-12-24 | No offline support for v1 | Keep complexity low for initial release |
| 2025-12-24 | 200m geofence radius | Standard radius covers parking lot, consistent across stores |
| 2025-12-24 | White logo for splash | Use logo_white.svg on gradient background |
| 2025-12-24 | Force re-login on access revocation | Clear tokens and redirect to login if store access removed |
| 2025-12-24 | TDD approach for implementation | Write tests before implementation for each component |
| 2025-12-24 | Full code replacement | Replace existing auth/user code per SDD rather than incremental updates |
| 2025-12-24 | Token refresh with request queuing | Queue concurrent requests during refresh to prevent race conditions |
| 2025-12-24 | Repository pattern | Create AuthRepository and ClockRepository for cleaner separation |
| 2025-12-24 | Email-only login | Change from username to email field per SDD spec |
| 2025-12-24 | Bottom sheet only for store picker | Skip full-screen StorePickerScreen route, use bottom sheet everywhere |
| 2025-12-24 | ShellRoute for bottom navigation | Use GoRouter ShellRoute for persistent nav instead of per-screen widget |
| 2025-12-24 | Location permission on first clock action | Not during login/onboarding |

## Context

**Initial Request:** Create an initial loading screen with a user login flow using the API specifications in `docs/employee-api.yaml`. UI should follow `docs/STYLE_GUIDE.md` using various shades of purple as primary colors.

**Key Requirements:**
- Initial splash/loading screen with branding
- Enhanced login flow using employee-api.yaml endpoints:
  - `/auth/login` - Email/password login
  - `/auth/pin-login` - PIN login
  - `/auth/refresh` - Token refresh
  - `/auth/logout` - Logout
- JWT token storage and refresh handling
- Purple-themed UI following STYLE_GUIDE.md

**Existing Context:**
- Flutter app with Clean Architecture + Riverpod
- Existing login_screen.dart with basic implementation
- app_colors.dart already defines purple palette per style guide
- API client with Dio + interceptors exists
- Storage service for tokens exists

---
*This file is managed by the specification-management skill.*