# tOS - Enterprise Web Operating System

![Next.js](https://img.shields.io/badge/Next.js-14.2-black?logo=next.js)
![NestJS](https://img.shields.io/badge/NestJS-10.3-red?logo=nestjs)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-blue?logo=postgresql)
![Keycloak](https://img.shields.io/badge/Keycloak-24-blue?logo=keycloak)
![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue?logo=typescript)
![License](https://img.shields.io/badge/License-Proprietary-gray)

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

---

## Inhaltsverzeichnis

- [Überblick](#überblick)
- [Tech-Stack](#tech-stack)
- [Projektstruktur](#projektstruktur)
- [Voraussetzungen](#voraussetzungen)
- [Installation & Setup](#installation--setup)
- [Scripts](#scripts)
- [Architektur](#architektur)
- [Module](#module)
- [API-Dokumentation](#api-dokumentation)
- [Datenbank](#datenbank)
- [Keycloak](#keycloak)
- [Umgebungsvariablen](#umgebungsvariablen)
- [Lizenz](#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

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

### 2. Dependencies installieren

```bash
pnpm install
```

### 3. Environment-Variablen einrichten

```bash
# 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

```bash
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`:

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

### 6. Datenbank-Schema anwenden

```bash
pnpm db:push
```

### 7. Datenbank mit Stammdaten befüllen

```bash
pnpm db:seed
```

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

### 8. Shared Package bauen

```bash
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

```bash
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

```bash
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