# tOS Backend Architecture Memory

## Project Structure
- **Location**: `/home/mehmed/Entwicklung/githubProjekte/tOS/apps/api/`
- **Framework**: NestJS 10.3.x with TypeScript strict mode
- **ORM**: Prisma 5.8.x with PostgreSQL
- **Auth**: JWT-based with Keycloak integration support

## Key Conventions
- **Language**: English for all code/comments
- **Files**: kebab-case, **Variables**: camelCase
- **API Prefix**: `/api/v1/`
- **Global Guards**: JwtAuthGuard -> RolesGuard -> PermissionsGuard
- **IDs**: CUID, **Soft Delete**: `isActive` boolean

## Security - Encryption (CRITICAL)
- `EncryptionService` in `src/common/services/` (AES-256-GCM)
- **Encrypted fields in Employee model:**
  - `salary` - Stored as encrypted String (not Decimal!)
  - `bankAccount` - Stored as encrypted JSON string
- Access via `findOne(id, includeSensitive=true)` for decryption
- Config: `ENCRYPTION_KEY` env variable (required in production)

## Auth Pattern
- Routes protected by default via global JwtAuthGuard
- `@Public()` for open endpoints
- `@Roles('admin', 'hr-manager')` for role-based access
- `@RequirePermissions(Permission.USERS_CREATE)` for fine-grained
- `@CurrentUser()` to get JWT payload

## Available Roles
admin, hr-manager, team-lead, employee

## Module Exports
All modules export via `index.ts` barrel files:
- `/modules/index.ts` exports: audit, dashboard, departments, user-preferences, integrations, lean, hr
- `/modules/lean/index.ts` exports: s3-planning, skill-matrix, morning-meeting
- `/modules/hr/index.ts` exports: employees, absences, time-tracking

## Health Endpoints
- Located at `src/health/` (NOT `src/modules/health/`)
- `GET /health` - Full check (database, memory, modules status)
- `GET /health/liveness` - Kubernetes liveness
- `GET /health/readiness` - Database connectivity
- `ModulesHealthIndicator` reports core/hr/lean/integrations status

## Test Infrastructure
- **Web (apps/web)**: Vitest 2.x + @testing-library/react + jsdom
  - Config: `apps/web/vitest.config.ts`
  - Setup: `apps/web/src/test/setup.ts` (imports @testing-library/jest-dom/vitest)
  - Scripts: `test` (vitest run), `test:watch` (vitest)
- **API (apps/api)**: Jest 29.x + ts-jest + @nestjs/testing
  - Config: inline in `package.json` under `jest` key
  - rootDir: `src`, testRegex: `.*\\.spec\\.ts$`
  - Module alias: `@/` -> `<rootDir>/`

## Phase 3: Integrations
Location: `src/modules/integrations/`
Sub-modules: credentials/, sync/, status/, jobs/
Types: PLENTYONE, ZULIP, TODOIST, FREESCOUT, NEXTCLOUD, ECODMS, GEMBADOCS

## Phase 4: LEAN
Location: `src/modules/lean/`
- `s3-planning/` - 3S/5S audit planning (permissions: S3_VIEW/CREATE/UPDATE/DELETE/MANAGE)
- `skill-matrix/` - Skills and employee skill entries
- `morning-meeting/` - SQCDM meetings, topics, actions (permissions: MEETING_VIEW/CREATE/UPDATE/DELETE)

## Phase 5: HR
Location: `src/modules/hr/`
- `employees/` - CRUD, org chart, **encrypted salary + bankAccount**
- `absences/` - Approval workflow (PENDING->APPROVED/REJECTED/CANCELLED)
- `time-tracking/` - Clock in/out, German ArbZG break compliance

### Absences Workflow
- Auto-approved: SICK, SICK_CHILD
- Vacation balance: 30 days/year, pro-rata by entry date

### Time Tracking
- German labor law breaks: >6h=30min, >9h=45min
- Monthly summary with overtime calculation

## Scripts (from root)
```bash
pnpm run dev:api     # Development server
pnpm run db:migrate  # Run migrations
pnpm run db:generate # Generate Prisma client
pnpm run db:seed     # Seed default data
```

## Common Patterns
- Use `CommonModule` (@Global) for shared services like EncryptionService
- DTOs with class-validator for input validation
- Swagger decorators for API documentation
- `@AuditLog('Entity', 'ACTION')` for audit trail

See detailed docs in `agent-memory/backend-specialist/` for:
- [integrations.md](./integrations.md) - Integration details
- [hr-module.md](./hr-module.md) - HR module specifics
- [testing.md](./testing.md) - Test infrastructure details