# 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)