tfm_ainventory/CODING_STANDARDS.md

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.