---
project_name: 'Brachnha'
user_name: 'Max'
date: '2026-01-21'
sections_completed: ['technology_stack', 'implementation_rules', 'naming_conventions', 'project_structure']
existing_patterns_found: 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.