---
project_name: 'Data_analysis'
user_name: 'Sepehr'
date: '2026-01-10'
sections_completed: ['technology_stack', 'language_rules', 'framework_rules', 'testing_rules', 'quality_rules', 'workflow_rules', 'anti_patterns']
status: 'complete'
rule_count: 18
optimized_for_llm: 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