# TFM aInventory - Coding Standards

**Status**: ACTIVE | **Last Updated**: 2026-04-26

---

## 1. General Principles
- **Language**: All code, variables, and documentation MUST be in **English**.
- **Modularity**: Files should be under **300 lines**. Extract logic into hooks (frontend) or services (backend).
- **Simplicity**: Strict Single Responsibility Principle (SRP). Complexity score < 10.

## 2. Backend (FastAPI / Python)
- **Framework**: FastAPI (Async/Await)
- **Validation**: Pydantic v2
- **Database**: SQLAlchemy 2.0 (Async) + Alembic migrations.
- **Testing**: Pytest. **Target Coverage: 85%+**.
- **Naming**: `snake_case` for variables/functions, `PascalCase` for classes.

## 3. Frontend (Next.js / TypeScript)
- **Framework**: Next.js 15+ (App Router, Strict TypeScript).
- **Styling**: Tailwind CSS (refer to `DESIGN_SYSTEM.md`).
- **State Management**: React Hooks + Dexie.js (Offline IndexDB).
- **Testing**: Vitest for unit, Playwright for E2E. **Target Coverage: 80%+**.
- **Naming**: `camelCase` for variables/functions, `PascalCase` for components.

## 4. Testing Strategy (MANDATORY)
- **Test-First**: Write and pass tests BEFORE refactoring or adding features.
- **Zero Regression**: 100% of existing tests must pass post-change.
- **Gating**:
  - Backend: `pytest backend/tests/`
  - Frontend: `npm run test`
  - E2E: `npx playwright test`

## 5. Security & Data Integrity
- **Restricted Actions**: DELETE requires Admin role.
- **Audit Immortality**: Deleting an item MUST NOT delete its `AuditLog` history.
- **Authentication**: Never bypassed, even in development. PBKDF2 for local, LDAP for enterprise.
- **Credentials**: Use `.env` or YAML config. NEVER hardcode or log secrets.
- **Confirmations**: Destructive actions require triple confirmation or native `window.confirm`.

## 6. Versioning & Workflow
- **Git**: Use `dev` branch for active work. Never push to `master` directly.
- **Versioning**: Run `python3 scripts/save_version.py` on every commit.
- **Documentation**: Every feature change MUST update: `README.md`, `USER_GUIDE.md`, `ARCHITECTURE.md`, `DEPLOYMENT.md`, and `ROADMAP.md`.