tOS - Enterprise Web Operating System

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

---

Inhaltsverzeichnis

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

---

Überblick

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)

---

Projektstruktur

tOS/
├── apps/
│   ├── web/                    # Next.js 14 Frontend (Port 3000)
│   │   ├── src/
│   │   │   ├── app/[locale]/   # App Router mit i18n
│   │   │   │   ├── (auth)/     # Geschützte Routen
│   │   │   │   └── login/      # Öffentliche 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 Übersetzungen (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
│       │   │   ├── user-preferences/ # Benutzereinstellungen
│       │   │   └── audit/      # Audit-Logging
│       │   └── common/         # Filter, Interceptors, Pipes
│       └── prisma/             # Schema, Migrations, Seed
│
├── packages/
│   └── shared/                 # Gemeinsame Typen & Utilities
│
├── docs/
│   └── integrations/           # API-Dokumentationen (z.B. PlentyONE Swagger)
│
├── 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

# 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 benötigten 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 benötigt 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 befüllen

pnpm db:seed

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

8. Shared Package bauen

pnpm --filter @tos/shared build

Das Shared Package muss vor dem ersten Start gebaut werden, da API und Web die kompilierten Typen benötigen.

9. 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-Prüfung
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 ausführen
pnpm db:seed	Stammdaten einspielen
pnpm db:studio	Prisma Studio öffnen

Docker

Script	Beschreibung
pnpm docker:up	Container starten
pnpm docker:down	Container stoppen
pnpm docker:ps	Container-Status anzeigen
pnpm docker:logs	Container-Logs anzeigen
pnpm docker:reset	Container + Volumes zurücksetzen

---

Architektur

Authentifizierung

Browser → Next.js (NextAuth) → Keycloak (OAuth2/OIDC)
                                      │
                                      ▼
Browser → Next.js → NestJS API (JWT Guard) → Keycloak (Token-Validierung)

• Frontend: NextAuth mit Keycloak-Provider, automatische Weiterleitung zum Keycloak-Login
• 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	Abteilungsübergreifende 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 über die Datenbank angepasst werden kann.

Frontend-Architektur

• App Router mit [locale] Segment für 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). Verfügbare Widgets:

Widget	Beschreibung
Welcome	Begrüßung mit Benutzerinfo
Clock	Digitale Uhr
Stats	KPI-Statistiken
Quick Actions	Schnellzugriff auf häufige Aktionen
Calendar	Kalenderübersicht
Activity	Aktivitätsfeed
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, Übersichten pro Mitarbeiter
• Abwesenheiten - Anträge, Genehmigungen, Kalenderansicht
• Organigramm - Visuelle Unternehmensstruktur

LEAN-Modul

• 3S-Planung - Seiri (Sortieren), Seiton (Systematisieren), Seiso (Säubern)
• 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, Präsenz
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 verfügbar:

http://localhost:3001/api/docs

Authentifizierung erfolgt über 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-Übersicht

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

Öffnet 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-nextauth	Confidential	NextAuth (Frontend-Authentifizierung)
tos-backend	Confidential	NestJS (Service-Account, Token-Validierung)

Hinweis: Der Client tos-nextauth muss einmalig manuell in der Keycloak Admin-Konsole angelegt werden. Der Realm-Export enthält nur tos-frontend und tos-backend. Siehe apps/web/.env für die benötigten Client-Einstellungen.

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-Signaturschlüssel
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-Schlüssel (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-Signaturschlüssel
KEYCLOAK_CLIENT_ID	Frontend-Client-ID
KEYCLOAK_CLIENT_SECRET	Frontend-Client-Secret
KEYCLOAK_ISSUER	Keycloak Issuer-URL

Vollständige Beispiele befinden sich in den jeweiligen .env.example-Dateien.

---

Lizenz

Proprietary - Tradeo GmbH. Alle Rechte vorbehalten.

teos