Initial commit: Data Analysis application with FastAPI backend and Next.js frontend

2026-01-11 21:54:33 +01:00
commit 7bdafb4fbf
549 changed files with 96211 additions and 0 deletions
--- a/.claude/claude.md
+++ b/.claude/claude.md
@@ -0,0 +1,163 @@
+# CLAUDE.md - BMAD v6 Project Memory
+
+## Project Identity
+**Project Name**: [Your Project Name]
+**Tech Stack**: Node.js 20+, Express, TypeScript, PostgreSQL, Jest
+**Status**: Active Development
+**Last Updated**: 2026-01-11
+
+---
+
+## 🎯 BMAD Agents & Their Roles (Never Deviate)
+
+### Phase 1: Planning (Agentic Planning)
+These agents create the **PRD** and **Architecture** documents:
+
+- **Analyst Agent** (`/analyst`)
+  - INPUT: User brief, business goals
+  - OUTPUT: `docs/prd.md` (complete product requirements)
+  - Role: Deep requirements analysis, user stories gathering
+
+- **PM Agent** (`/pm`)
+  - INPUT: PRD from Analyst
+  - OUTPUT: Epic backlog + prioritized stories
+  - Role: Refine PRD, create backlog for SM
+
+- **Architect Agent** (`/architect`)
+  - INPUT: PRD + tech preferences
+  - OUTPUT: `docs/architecture.md` (system design, ADRs, constraints)
+  - Role: Technical decisions, architecture patterns, tech stack alignment
+
+### Phase 2: Development (Context-Engineered Development)
+These agents consume Story Files (created by SM):
+
+- **Scrum Master Agent** (`/sm`)
+  - INPUT: Backlog from PM + Architecture from Architect
+  - OUTPUT: `docs/stories/X.Y.story-name.md` (implementation-ready)
+  - **CRITICAL**: SM embeds **full context** into each story:
+    - Architecture Decision References (ADRs)
+    - Acceptance Criteria (exact, testable)
+    - Implementation Guidance
+    - Dependencies & testing requirements
+  - Role: Create stories that Dev agent can execute with **zero ambiguity**
+
+- **Dev Agent** (`/dev`)
+  - INPUT: A single Story File + referenced Architecture
+  - OUTPUT: Code implementation + tests + PR
+  - **CRITICAL**: Dev agent should ONLY read:
+    1. The current story file (reference with `@docs/stories/X.Y.story-name.md`)
+    2. Architecture from `docs/architecture.md` (or specific ADR)
+    3. Tech Stack patterns from `/src` code
+  - Role: Execute, don't invent
+
+- **QA Agent** (`/qa`)
+  - INPUT: Dev's implementation + story file
+  - OUTPUT: Validation checklist, defect list or verification
+  - Role: Validate against acceptance criteria
+
+---
+
+## 📂 Context Locations (Where Each Agent Reads/Writes)
+
+### Agent Reads
+| Agent | Reads From | Purpose |
+|-------|-----------|---------|
+| Analyst | Business brief (input by you) | Understand requirements |
+| PM | Analyst's PRD | Create backlog |
+| Architect | PRD + tech preferences | Design system |
+| SM | Backlog + Architecture + code patterns | Create story specs |
+| Dev | Story file + Architecture refs | Implement feature |
+| QA | Story file + Dev output | Validate |
+
+### Agent Writes
+| Agent | Writes To | Format |
+|-------|-----------|--------|
+| Analyst | `docs/prd.md` | Markdown |
+| PM | Backlog (in chat or `docs/epics.md`) | Markdown |
+| Architect | `docs/architecture.md` | Markdown (with ADR sections) |
+| SM | `docs/stories/X.Y.description.md` | Markdown (detailed specs) |
+| Dev | `src/`, `tests/` | Code + Test files |
+| QA | Validation in chat + update story status | Markdown checklist |
+
+---
+
+## 🏗️ Architecture Constraints (MUST NOT BREAK)
+
+**These are decided once, NEVER change mid-project without team review:**
+
+### API Design Pattern
+- Gateway Pattern: Single entry point (`/api`)
+- Routes: RESTful `/api/v1/[resource]/[action]`
+- Authentication: JWT at Gateway level (not per-route)
+- Error responses: Standardized JSON with `code`, `message`, `details`
+
+### Database Layer
+- ORM: Prisma (never raw SQL)
+- Migrations: One per feature, committed to git
+- Schema: Timestamps (`createdAt`, `updatedAt`) on all tables
+- Transactions: Always wrap multi-step operations
+
+### Async Processing
+- Queue Library: Bull
+- Message Broker: Redis
+- Pattern: Email sends, notifications, heavy computation → queued
+- Retry policy: 3 attempts, exponential backoff
+
+### Authentication & Security
+- Password hashing: bcrypt (library: bcryptjs)
+- JWT signing key: Stored in `.env`, never in code
+- CORS: Whitelist explicit domains
+- Rate limiting: 100 req/minute per IP
+
+### Testing
+- Framework: Jest
+- Coverage minimum: 80%
+- Tests near code: `*.test.ts` in same folder as source
+- Test data: Use fixtures in `tests/fixtures/`
+
+### Code Style
+- Language: TypeScript (strict mode always)
+- Linter: ESLint + Prettier
+- Commit format: `feat(module): description` or `fix(module): description`
+- Branch strategy: Feature branches only, PR + review before merge
+
+---
+
+## 📝 Story File Structure (How SM Formats Each Story)
+
+When SM creates a story, it MUST include ALL of this (Dev relies on it):
+
+```markdown
+# Story X.Y: [Feature Name]
+
+## Objective
+[One sentence: What we're building and why]
+
+## Acceptance Criteria (Gherkin Format)
+Given [context]
+When [action]
+Then [result]
+
+[Repeat for each criterion]
+
+## Architecture References
+- See: docs/architecture.md → "API Design Pattern" section
+- See: docs/architecture.md → "Authentication" ADR
+- Pattern used: [Specific pattern name]
+
+## Implementation Guidance
+- Files to create: [list]
+- Files to modify: [list]
+- Patterns to follow: [reference code examples]
+- Tests required: [specific test cases]
+
+## Dependencies
+- Depends on: Story X.Y (must be DONE first)
+- Blocks: Story X.Z (cannot start until this is merged)
+
+## Definition of Done
+- [ ] Code passes linter (ESLint)
+- [ ] Tests written & passing (Jest, >80% for this file)
+- [ ] Database migration added (if needed)
+- [ ] Story status updated in docs/stories/
+- [ ] PR created with reference to this story