tfm_ainventory/AGENTS.md

AGENTS.md — Web App Project Rules

Tech Stack

• Frontend: Next.js 15, React 19, TypeScript 5
• Styling: Tailwind CSS v3.4, Lucide React (Icons)
• Backend: Python 3.14, FastAPI, Uvicorn
• Database: SQLite (SQLAlchemy) + Dexie (IndexedDB pentru offline-first)
• AI & Vision: Google Gemini 2.0 (Vision), Tesseract.js (Local OCR)
• Infrastructure: Docker, Caddy (Automatic SSL Reverse Proxy)
• Security: JWT (python-jose), LDAP (Enterprise Integration)

Code Quality

• Keep cyclomatic complexity under 10 per function
• Aim for files under 300 lines
• All files must follow single responsibility principle (one clear purpose per module)
• Extract complex logic into reusable utilities/services

Testing

Standard Testing (Ongoing)

• Write unit tests for all utility functions
• Minimum 80% coverage on new code
• Use Vitest for unit tests

AI-Friendly Refactoring Testing Strategy (v1.10.16+)

Scope: Full test coverage before refactoring to prevent UI/functionality regression.

Backend Testing (Pytest)

• Target: 85%+ coverage (unit + integration tests)
• Structure: backend/tests/ with suites for routers, models, auth, AI pipeline
• Coverage tools: pytest backend/tests/ --cov=backend --cov-report=html
• Test types: Unit (functions), Integration (full API workflows), Fixtures (mocked auth, in-memory DB)

Frontend Testing (Vitest)

• Target: 80%+ coverage (components, hooks, snapshots)
• Structure: frontend/tests/ with component tests, hook tests, integration workflows
• Coverage tools: npm test -- --coverage
• Test types: Component rendering, Hook state/side effects, Snapshot tests for UI layouts

E2E Testing (Playwright)

• Target: Critical user workflows automated
• Workflows: Login, Scan → Match → Stock adjustment, New Item (AI), Admin config, Offline sync
• Runtime: ~30 min total
• Command: npx playwright test

Test-First Approach

• All tests written and passing BEFORE refactoring any code
• Tests serve as gating condition: no code changes if tests fail
• Functional preservation: Zero behavior changes post-refactor
• Regression prevention: Manual checklist + automated tests catch UI breakage

Security

• Store all secrets in inventory.env — never hardcode credentials
• Never log API keys, tokens or passwords
• Validate all user input before processing

Git Conventions

• Use conventional commits (feat:, fix:, docs:, refactor:, test:, etc.)
• Keep PRs under 400 lines of diff when possible
• Refactoring commits: refactor: split {module} into smaller modules
• Testing commits: test: add {suite} coverage for {module}
• All commits must have passing test suite before merge

Refactoring Guidelines (AI-Friendly Modularity)

Refactoring Principles

• Target: Break monolithic files into focused modules (<300 lines each)
• Priority Order: Backend routers → Components → Pages
• No Behavior Changes: Every refactor must pass 100% of existing tests
• Gating Rule: No refactor commit unless all tests pass (pre + post)
• Regression Prevention: Manual checklist + automated tests validate UI integrity

Refactoring Process

1. Ensure full test coverage exists (backend 85%, frontend 80%)
2. Run complete test suite (all tests PASS)
3. Refactor module: split into smaller files/services
4. Run test suite again (all tests PASS)
5. Manual browser validation: UI unchanged, all buttons/features work
6. Commit with test results in message body
7. Move to next module

Module Extraction Patterns

• Backend Routers: Split into router (endpoints only) + service (business logic) + validators (input validation)
• Components: Split into orchestrator component + sub-components + custom hooks for state/logic
• Pages: Extract page logic into custom hooks, move forms into separate components
• Utilities: Consolidate repeated logic into lib/ or services/ modules

Validation Checklist (Post-Refactor)

• All pytest tests passing (backend coverage 85%+)
• All vitest tests passing (frontend coverage 80%+)
• All e2e workflows passing (Playwright)
• Login works (LDAP + local)
• Scanner functional (scan → match → stock adjustment)
• AI extraction working (new item → AI popup → validation)
• Admin page responsive and functional
• No console errors in browser
• Mobile responsive (320px, 768px, 1024px+ viewports)
• Keyboard navigation works (focus indicators visible)