Files

Flexomatic81 fe305f6fc8 feat: complete tOS project with HR, LEAN, Dashboard and Integrations modules

Full enterprise web operating system including:
- Next.js 14 frontend with App Router, i18n (DE/EN), shadcn/ui
- NestJS 10 backend with Prisma, JWT auth, Swagger docs
- Keycloak 24 SSO with role-based access control
- HR module (employees, time tracking, absences, org chart)
- LEAN module (3S planning, morning meeting SQCDM, skill matrix)
- Integrations module (PlentyONE, Zulip, Todoist, FreeScout, Nextcloud, ecoDMS, GembaDocs)
- Dashboard with customizable drag & drop widget grid
- Docker Compose infrastructure (PostgreSQL 16, Redis 7, Keycloak 24)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-06 19:37:55 +01:00

3.9 KiB

Raw Blame History

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)

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 - Integration details
hr-module.md - HR module specifics
testing.md - Test infrastructure details

3.9 KiB Raw Blame History