brachnha-insight/_bmad-output/project-context.md

project_name, user_name, date, sections_completed, existing_patterns_found

project_name	user_name	date	sections_completed	existing_patterns_found
Test01	Max	2026-01-21	technology_stack implementation_rules naming_conventions project_structure	12

Project Context for AI Agents

This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss.

---

Technology Stack & Versions

• Framework: Next.js 14+ (App Router)
• Language: TypeScript (Strict Mode)
• Styling: Tailwind CSS, ShadCN UI
• State Management: Zustand v5
• Database (Client): Dexie.js v4.2.1 (IndexedDB Wrapper)
• Auth: Auth.js v5 (Beta)
• Runtime: Vercel Edge Runtime (for API Routes)

Critical Implementation Rules

1. The "Logic Sandwich" Pattern (Service Layer)

• Rule: UI Components must NEVER import lib/db directly.
• Pattern: UI Component -> Zustand Store -> Service Layer -> Dexie/LLM.
• Why: To strictly decouple the View from the Data Complexity (syncing, offline queue).
• Enforcement: Services must return plain data objects, not Dexie observables.

2. State Management (Zustand)

• Rule: ALWAYS use atomic selectors.
• Bad: const { messages } = useChatStore()
• Good: const messages = useChatStore((s) => s.messages)
• Why: To prevent unnecessary re-renders in the high-frequency chat UI.

3. Local-First Data Boundary

• Rule: IndexedDB is the Source of Truth for User Data.
• Constraint: The LLM API is a compute engine, not a storage provider. Do not send user data to the server for persistence.
• Offline: All "Venting" actions must be queued in the Client-Side Transaction Log if offline.

4. Edge Runtime Constraint

• Rule: All API routes under app/api/ must use the Edge Runtime.
• Code: export const runtime = 'edge';
• Why: To ensure <3s cold start latency for critical interactions.

Naming Conventions

• React Components: PascalCase (e.g., ChatWindow.tsx)
• Database Tables: camelCase (e.g., chatLogs)
• API Endpoints: kebab-case (e.g., /api/chat-sessions)
• Internal Functions: verbNoun (e.g., fetchUserSession)

Project Structure Highlights

• src/app: Routes only. Minimal logic.
• src/components/features: Feature-specific logic (Smart components).
• src/components/ui: Dumb/Primitive ShadCN components.
• src/services: Business logic and Database orchestration.
• src/lib/db: Dexie schema and client definition.