62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
---
|
|
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
|