Flexomatic81
fe305f6fc8
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>
100 lines
3.9 KiB
Markdown
100 lines
3.9 KiB
Markdown
# 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
|