Analysis/_bmad-output/project-context.md

project_name	user_name	date	sections_completed	status	rule_count	optimized_for_llm
Data_analysis	Sepehr	2026-01-10	technology_stack language_rules framework_rules testing_rules quality_rules workflow_rules anti_patterns	complete	18	true

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

• Backend: Python 3.12, FastAPI, Pydantic v2, Pandas, Scikit-learn, Statsmodels, PyArrow v17.0+ (Managed by uv)
• Frontend: Next.js 16 (Standalone mode), TypeScript, Tailwind CSS, Shadcn UI, TanStack Table, Recharts, Zustand v5, TanStack Query v5, Apache Arrow v17+
• DevOps: Docker, Docker Compose, multi-stage builds (distroless/alpine)

Critical Implementation Rules

Language & Framework Patterns

• Backend (Python): PEP 8 (snake_case). Pydantic v2 for schema validation. Fast API async def for I/O bound routes.
• Frontend (TSX): Shadcn UI + Tailwind. Feature-based organization in src/features/.
• Performance: Use apache-arrow for data-heavy components. Virtualize all grids with 500+ rows.

Data & State Architecture

• API Convention: snake_case JSON keys to maintain consistency with Pandas DataFrame columns.
• Serialization: pyarrow.ipc for binary streams to ensure zero-copy data transfer between services.
• State Management: Zustand for localized UI/Grid state; TanStack Query for remote server state.

Testing & Quality

• Location: Centralized /tests directory at each service root (backend/tests/, frontend/tests/).
• Standard: Use pytest for Python and vitest for TypeScript.
• Documentation: Every exported function must have Docstrings/JSDoc explaining parameters and return types.

Critical Anti-Patterns (DO NOT)

• ❌ DO NOT use standard JSON for transferring datasets > 5,000 rows (use Apache Arrow).
• ❌ DO NOT use deep React Context for high-frequency state updates (use Zustand).
• ❌ DO NOT implement "Black Box" algorithms; all data exclusions must be logged and visualized in the InsightPanel.
• ❌ DO NOT perform heavy blocking computations on the main FastAPI process; use background tasks for jobs expected to take > 5 seconds.

---

Usage Guidelines

For AI Agents:

• Read this file before implementing any code.
• Follow ALL rules exactly as documented.
• When in doubt, prefer the more restrictive option.
• Update this file if new patterns emerge.

For Humans:

• Keep this file lean and focused on agent needs.
• Update when technology stack changes.
• Review quarterly for outdated rules.

Last Updated: 2026-01-10