# Implementation Plan: Bottom Navigation with Chat Entry

**Branch**: `001-bottom-nav` | **Date**: 2025-12-06 | **Spec**: specs/001-bottom-nav/spec.md
**Input**: Feature specification from `/specs/001-bottom-nav/spec.md`

## Summary

Add a persistent bottom navigation with Home, Store, Chat, and Settings, preserving tab state, surfacing store context/switching, and exposing a chat entry placeholder that handles offline gracefully. Approach: use existing Riverpod-owned navigation state and GoRouter routes, reuse store context providers for selection, and add a resilient chat container that communicates availability while keeping navigation responsive.

## Technical Context

**Language/Version**: Flutter 3.38.3 / Dart 3.10.1  
**Primary Dependencies**: Riverpod 3.x AsyncNotifier, GoRouter 17.x, Dio via `api_client.dart`, shared UI per `STYLE_GUIDE.md`  
**Storage**: Existing secure storage for API keys/session; no new persistence introduced  
**Testing**: `flutter test` with unit + widget coverage for providers/navigation and state preservation  
**Target Platform**: iOS/Android BuyerKiosk app  
**Project Type**: Mobile client  
**Performance Goals**: 60 fps UI; tab switches feel instant; store switch under 10s incl. fetch  
**Constraints**: Offline-friendly navigation; respect auth guards and 403-clearing of keys  
**Scale/Scope**: Multi-screen kiosk app with shared layout; new work touches bottom nav + store/chat entry points

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Architecture fit: Navigation/UI work stays in `presentation` with GoRouter routes and Riverpod-owned state; store context via existing providers; no exceptions expected.
- API contract fidelity: Store list/context endpoints reused via `api_client.dart`; no new endpoints or mapper changes; enforce POST + API key where called.
- Auth/permission coverage: Bottom nav shown post-auth only; tabs honor existing `AppPage` guards; store switching limited to users with multiple stores; 403 continues to clear cached keys.
- UX resilience: Loading/empty/error states defined for Store; offline messaging for Store/Chat; adhere to `STYLE_GUIDE.md`; navigation remains responsive even offline.
- Testing plan: Widget tests for bottom nav rendering, active tab, and guard visibility; provider tests for store selection state; navigation tests for GoRouter tab routing; offline/error state widget coverage; run `flutter test` before merge.

## Project Structure

### Documentation (this feature)

```text
specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```

```text
lib/
├── core/                 # constants, api client, utilities
├── data/                 # models, repositories using Dio/api_client
├── domain/               # entities and use cases for store context
├── presentation/         # widgets/screens; bottom nav, store selector, chat placeholder, settings/home screens
├── router/               # GoRouter setup, auth guards, route definitions
└── common/               # shared UI components per STYLE_GUIDE.md

test/
├── presentation/         # widget tests for nav, store tab, chat placeholder states
├── domain/               # provider/state tests (store context, nav state)
└── router/               # navigation/guard tests
```

**Structure Decision**: Single Flutter mobile app; work lands in `lib/presentation` for UI, `lib/router` for tab routes/guards, and `lib/domain`/`lib/data` where store context is managed; tests mirror under `test/`.

## Complexity Tracking

> **Fill ONLY if Constitution Check has violations that must be justified**

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |