3fbbb1a93b
- Next.js 14+ with App Router and TypeScript - Tailwind CSS and ShadCN UI styling - Zustand state management - Dexie.js for IndexedDB (local-first data) - Auth.js v5 for authentication - BMAD framework integration Co-Authored-By: Claude <noreply@anthropic.com>
63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
---
|
|
project_name: 'Test01'
|
|
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.
|