tOS - Enterprise Web Operating System

Ein webbasiertes Enterprise-Dashboard, das verschiedene Unternehmenssysteme integriert und einen zentralen LEAN-Management-Bereich bietet.

---

Inhaltsverzeichnis

• Ueberblick
• Tech-Stack
• Projektstruktur
• Voraussetzungen
• Installation & Setup
• Scripts
• Architektur
• Module
• API-Dokumentation
• Datenbank
• Keycloak
• Umgebungsvariablen
• Lizenz

---

Ueberblick

tOS ist ein modulares Enterprise Operating System mit folgenden Kernbereichen:

• Dashboard - Anpassbares Widget-Dashboard mit Drag & Drop
• HR - Mitarbeiterverwaltung, Zeiterfassung, Abwesenheiten, Organigramm
• LEAN - 3S-Planung, Morning Meeting (SQCDM), Skill Matrix
• Integrations - Anbindung an 7 externe Systeme
• Admin - Benutzer-, Abteilungs- und Systemverwaltung

---

Tech-Stack

Bereich	Technologien
Frontend	Next.js 14, React 18, TanStack Query, Zustand, Tailwind CSS, shadcn/ui, Framer Motion
Backend	NestJS 10, Prisma 5, Passport JWT, Swagger
Datenbank	PostgreSQL 16, Redis 7
Auth	Keycloak 24, NextAuth 4
Infrastruktur	Docker Compose, pnpm 9, Turborepo
Sprachen	TypeScript 5.6, i18n via next-intl (DE/EN)
Testing	Vitest (Frontend), Jest (Backend)

---

Projektstruktur

tOS/
├── apps/
│   ├── web/                    # Next.js 14 Frontend (Port 3000)
│   │   ├── src/
│   │   │   ├── app/[locale]/   # App Router mit i18n
│   │   │   │   ├── (auth)/     # Geschuetzte Routen
│   │   │   │   └── login/      # Oeffentliche Login-Seite
│   │   │   ├── components/     # React-Komponenten (ui, layout, dashboard, hr, lean)
│   │   │   ├── hooks/          # Custom Hooks (hr, lean, integrations)
│   │   │   ├── lib/            # Utilities, API-Client, Auth-Config
│   │   │   ├── stores/         # Zustand State Management
│   │   │   └── types/          # TypeScript-Typen
│   │   └── messages/           # i18n Uebersetzungen (de.json, en.json)
│   │
│   └── api/                    # NestJS 10 Backend (Port 3001)
│       ├── src/
│       │   ├── auth/           # JWT Guards, Rollen, Permissions
│       │   ├── modules/
│       │   │   ├── hr/         # Mitarbeiter, Abwesenheiten, Zeiterfassung
│       │   │   ├── lean/       # Skill Matrix, Morning Meeting, 3S-Planung
│       │   │   ├── integrations/ # 7 API-Connectoren + Sync
│       │   │   ├── dashboard/  # Widget-Daten & Statistiken
│       │   │   ├── departments/# Abteilungsverwaltung
│       │   │   └── audit/      # Audit-Logging
│       │   └── common/         # Filter, Interceptors, Pipes
│       └── prisma/             # Schema, Migrations, Seed
│
├── packages/
│   └── shared/                 # Gemeinsame Typen & Utilities
│
├── docker/
│   ├── docker-compose.yml      # PostgreSQL, Redis, Keycloak
│   ├── keycloak/               # Realm-Export & Config
│   └── .env.example
│
└── turbo.json                  # Turborepo Build-Pipeline

---

Voraussetzungen

Software	Version
Node.js	>= 20.0.0
pnpm	>= 9.0.0
Docker	>= 24.0
Docker Compose	>= 2.20

---

Installation & Setup

1. Repository klonen

git clone https://github.com/Tradeo-GmbH/tOS.git
cd tOS

2. Dependencies installieren

pnpm install

3. Environment-Variablen einrichten

# Root
cp .env.example .env

# Docker
cp docker/.env.example docker/.env

# Backend
cp apps/api/.env.example apps/api/.env

# Frontend
cp apps/web/.env.example apps/web/.env

Die .env.example-Dateien enthalten alle benoetigten Variablen mit Entwicklungs-Standardwerten.

4. Docker-Services starten

pnpm docker:up

Startet PostgreSQL (5432), Redis (6379) und Keycloak (8080).

5. Anwendungs-Datenbank erstellen

Keycloak verwendet die Datenbank tos_db. Die Anwendung benoetigt eine separate Datenbank tos_app:

docker exec -it tos-postgres psql -U tos_user -d tos_db -c "CREATE DATABASE tos_app;"

6. Datenbank-Schema anwenden

pnpm db:push

7. Datenbank mit Stammdaten befuellen

pnpm db:seed

Erstellt Rollen (admin, hr-manager, team-lead, employee), Abteilungen und einen Entwickler-Admin-Benutzer.

8. Entwicklungsserver starten

pnpm dev

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:3001/api
Swagger Docs	http://localhost:3001/api/docs
Keycloak Admin	http://localhost:8080 (admin/admin)

---

Scripts

Entwicklung

Script	Beschreibung
pnpm dev	Alle Apps im Dev-Modus starten
pnpm dev:web	Nur Frontend starten
pnpm dev:api	Nur Backend starten
pnpm build	Alle Apps bauen
pnpm typecheck	TypeScript-Pruefung
pnpm lint	Code-Linting
pnpm format	Code-Formatierung

Datenbank

Script	Beschreibung
pnpm db:generate	Prisma Client generieren
pnpm db:push	Schema in die Datenbank pushen
pnpm db:migrate	Migrationen ausfuehren
pnpm db:seed	Stammdaten einspielen
pnpm db:studio	Prisma Studio oeffnen

Docker

Script	Beschreibung
pnpm docker:up	Container starten
pnpm docker:down	Container stoppen
pnpm docker:logs	Container-Logs anzeigen
pnpm docker:reset	Container + Volumes zuruecksetzen

Tests

Script	Beschreibung
pnpm test	Alle Tests ausfuehren
pnpm test:watch	Tests im Watch-Modus
pnpm test:e2e	End-to-End-Tests

---

Architektur

Authentifizierung

Browser -> Next.js (NextAuth) -> Keycloak (OAuth2/OIDC)
                                      |
                                      v
Browser -> Next.js -> NestJS API (JWT Guard) -> Keycloak (Token-Validierung)

• Frontend: NextAuth mit Keycloak-Provider (JWT-Strategie)
• Backend: Passport-JWT mit globalem Guard (@Public() zum Deaktivieren)
• Guard-Kette: JWT -> Rollen -> Permissions

Rollen-System

Rolle	Beschreibung
admin	Vollzugriff auf alle Bereiche
hr-manager	HR-Verwaltung + LEAN-Zugriff
manager	Abteilungsuebergreifende Sicht
department_head	Abteilungsleitung
team-lead	Teamleitung mit direkten Reports
employee	Standard-Mitarbeiterzugriff

Permissions

Feingranulare Berechtigungen pro Modul (z.B. EMPLOYEES_VIEW, ABSENCES_APPROVE, INTEGRATIONS_MANAGE). Jede Rolle hat ein vorkonfiguriertes Permission-Set, das ueber die Datenbank angepasst werden kann.

Frontend-Architektur

• App Router mit [locale] Segment fuer i18n
• Server/Client Split: page.tsx (Server) -> *-content.tsx (Client)
• State Management: Zustand (UI-State), TanStack Query (Server-State)
• Component Library: shadcn/ui auf Radix UI Basis

---

Module

Dashboard

Anpassbares Widget-Grid mit Drag & Drop (dnd-kit). Verfuegbare Widgets:

Widget	Beschreibung
Welcome	Begruessung mit Benutzerinfo
Clock	Digitale Uhr
Stats	KPI-Statistiken
Quick Actions	Schnellzugriff auf haeufige Aktionen
Calendar	Kalenderuebersicht
Activity	Aktivitaetsfeed
Orders	PlentyONE Bestellungen
Chat	Zulip Nachrichten
Tasks	Todoist Aufgaben
Tickets	FreeScout Tickets
Files	Nextcloud Dateien
Documents	ecoDMS Dokumente
GembaDocs	Audit-Dokumente

HR-Modul

• Mitarbeiterverwaltung - CRUD, Detailansicht, Neuanlage
• Zeiterfassung - Stempeluhr, Uebersichten pro Mitarbeiter
• Abwesenheiten - Antraege, Genehmigungen, Kalenderansicht
• Organigramm - Visuelle Unternehmensstruktur

LEAN-Modul

• 3S-Planung - Seiri (Sortieren), Seiton (Systematisieren), Seiso (Saeubern)
• Morning Meeting - SQCDM-Board (Safety, Quality, Cost, Delivery, Morale)
• Skill Matrix - Kompetenzerfassung und -bewertung pro Abteilung

Integrations-Modul

7 externe Systeme mit einheitlicher Connector-Architektur:

System	Typ	Funktionen
PlentyONE	ERP	Bestellungen, Artikel, Kontakte
Zulip	Chat	Nachrichten, Streams, Praesenz
Todoist	Tasks	Aufgaben, Projekte
FreeScout	Helpdesk	Tickets, Konversationen
Nextcloud	Cloud	Dateien, Ordner, Freigaben
ecoDMS	DMS	Dokumente, Klassifizierung
GembaDocs	Audit	Audits, Findings, Compliance

Admin-Bereich

• Benutzerverwaltung - Rollen zuweisen, Benutzer verwalten
• Abteilungen - Abteilungsstruktur pflegen
• Integrations-Admin - Credentials und Sync-Jobs verwalten

---

API-Dokumentation

Die interaktive API-Dokumentation ist via Swagger UI verfuegbar:

http://localhost:3001/api/docs

Authentifizierung erfolgt ueber Bearer JWT-Token. Die API ist in folgende Bereiche unterteilt:

• auth - Authentifizierung
• users - Benutzerverwaltung
• departments - Abteilungen
• hr/* - HR-Endpunkte (Mitarbeiter, Abwesenheiten, Zeiterfassung)
• lean/* - LEAN-Endpunkte (3S, Morning Meeting, Skill Matrix)
• integrations/* - Integrations-Endpunkte (pro Connector)
• dashboard - Dashboard-Daten

---

Datenbank

Zwei-Datenbanken-Setup

Datenbank	Verwendung
tos_db	Keycloak (wird automatisch erstellt)
tos_app	Anwendungsdaten (muss manuell erstellt werden)

Beide laufen auf derselben PostgreSQL-Instanz.

Schema-Uebersicht

Bereich	Modelle
Core	User, Department, Role, UserRole
HR	Employee, TimeEntry, Absence, EmployeeReview, OnboardingTask
LEAN	S3Plan, S3Category, S3Status, MorningMeeting, MorningMeetingTopic, MorningMeetingAction, Skill, SkillMatrixEntry
Integrations	IntegrationCredential, IntegrationSyncHistory
System	UserPreference, AuditLog

Prisma Studio

pnpm db:studio

Oeffnet eine Web-UI zur direkten Datenbank-Inspektion unter http://localhost:5555.

---

Keycloak

Realm-Konfiguration

Der Realm tOS wird beim Start automatisch aus docker/keycloak/realm-export.json importiert.

Clients

Client	Typ	Verwendung
tos-frontend	Confidential	NextAuth (Frontend-Authentifizierung)
tos-backend	Confidential	NestJS (Service-Account, Token-Validierung)

Rollen & Gruppen

Realm-Rollen: admin, hr-manager, manager, department_head, team-lead, employee

Gruppen: Administrators, Management, sowie Abteilungen (Sales, Accounting, Warehouse, Logistics, Engineering, IT, Executive, HR, Procurement)

Admin-Konsole

http://localhost:8080
Benutzer: admin
Passwort: admin

---

Umgebungsvariablen

Docker (docker/.env)

Variable	Beschreibung	Standard
POSTGRES_USER	Datenbankbenutzer	tos_user
POSTGRES_PASSWORD	Datenbankpasswort	tos_secret_password
POSTGRES_DB	Keycloak-Datenbank	tos_db
KEYCLOAK_ADMIN	Keycloak-Admin	admin
KEYCLOAK_ADMIN_PASSWORD	Keycloak-Admin-Passwort	admin

Backend (apps/api/.env)

Variable	Beschreibung
DATABASE_URL	PostgreSQL Connection String (tos_app)
PORT	API-Port (3001)
JWT_SECRET	JWT-Signaturschluessel
KEYCLOAK_URL	Keycloak-URL
KEYCLOAK_REALM	Realm-Name (tOS)
KEYCLOAK_CLIENT_ID	Backend-Client-ID
KEYCLOAK_CLIENT_SECRET	Backend-Client-Secret
REDIS_HOST / REDIS_PORT	Redis-Verbindung
ENCRYPTION_KEY	AES-256-Schluessel (32 Bytes)
SWAGGER_ENABLED	Swagger UI aktivieren
ENABLE_SYNC_JOBS	Integrations-Sync aktivieren

Frontend (apps/web/.env)

Variable	Beschreibung
NEXT_PUBLIC_API_URL	Backend-API-URL
NEXT_PUBLIC_APP_URL	Frontend-URL
NEXTAUTH_URL	NextAuth-Callback-URL
NEXTAUTH_SECRET	NextAuth-Signaturschluessel
KEYCLOAK_CLIENT_ID	Frontend-Client-ID
KEYCLOAK_CLIENT_SECRET	Frontend-Client-Secret
KEYCLOAK_ISSUER	Keycloak Issuer-URL

Vollstaendige Beispiele befinden sich in den jeweiligen .env.example-Dateien.

---

Lizenz

Proprietary - Tradeo GmbH. Alle Rechte vorbehalten.