chore: project initialization with infrastructure definition and structure

- Generate SSH deployment key (Ed25519) for server access
- Define complete server infrastructure (ProxmoxVE VM, Docker, networking)
- Create ACCESS.md with all connection details and SSH instructions
- Create INFRASTRUCTURE.md with VM setup guide and service architecture
- Set up project directory structure per briefing specification
- Add .env.example with all required environment variables
- Add .gitignore for Node.js/Docker/TypeScript project
- Create comprehensive README.md for developer onboarding
- Add Summarize.md changelog
- Include concept and briefing documents

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

.env.example

@@ -0,0 +1,77 @@
+# ============================================================
+# INSIGHT MVP - Umgebungsvariablen
+# ============================================================
+# Kopiere diese Datei nach .env und befuelle die Werte.
+# .env wird NIEMALS in Git committed!
+# ============================================================
+
+# --- Allgemein ---
+NODE_ENV=development
+APP_PORT=3000
+APP_URL=https://insight-dev.xinion.lan
+FRONTEND_URL=https://insight-dev.xinion.lan
+LOG_LEVEL=info
+
+# --- PostgreSQL ---
+DB_HOST=pgbouncer
+DB_PORT=6432
+DB_USER=insight
+DB_PASSWORD=                    # Sicheres Passwort setzen!
+DB_NAME=platform_core
+DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}
+
+# Direktverbindung (fuer Prisma Migrate, umgeht PgBouncer)
+DB_DIRECT_HOST=postgres
+DB_DIRECT_PORT=5432
+DATABASE_URL_DIRECT=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_DIRECT_HOST}:${DB_DIRECT_PORT}/${DB_NAME}
+
+# --- Redis ---
+REDIS_HOST=redis
+REDIS_PORT=6379
+REDIS_PASSWORD=                 # Optional, aber empfohlen
+
+# --- JWT (RS256) ---
+JWT_PRIVATE_KEY_PATH=/app/keys/jwt-private.pem
+JWT_PUBLIC_KEY_PATH=/app/keys/jwt-public.pem
+JWT_ACCESS_TOKEN_EXPIRY=15m
+JWT_REFRESH_TOKEN_EXPIRY=7d
+JWT_ISSUER=insight-platform
+
+# --- Bcrypt ---
+BCRYPT_COST=12
+
+# --- CORS ---
+CORS_ORIGINS=https://insight-dev.xinion.lan
+
+# --- Rate Limiting ---
+THROTTLE_TTL=60000
+THROTTLE_LIMIT=200
+
+# --- Traefik ---
+TRAEFIK_DASHBOARD_USER=admin
+TRAEFIK_DASHBOARD_PASSWORD=     # htpasswd Hash
+
+# --- step-ca (mTLS) ---
+STEP_CA_URL=https://step-ca:9000
+STEP_CA_FINGERPRINT=            # step-ca Root CA Fingerprint
+
+# --- SMTP (fuer Einladungs-E-Mails) ---
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASSWORD=
+SMTP_FROM=noreply@xinion.de
+
+# --- Observability ---
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=         # Sicheres Passwort setzen!
+
+# --- MS SSO (Beta - noch nicht aktiv) ---
+# MS_SSO_CLIENT_ENCRYPTION_KEY=  # AES-256 Key fuer Client Secret Verschluesselung
+
+# --- KI-Hilfe-Chat (optional) ---
+# ANTHROPIC_API_KEY=             # Claude API Key
+# AI_CHAT_ENABLED=false
+
+# --- DeepL (optional, fuer Hilfesystem-Uebersetzungen) ---
+# DEEPL_API_KEY=

.gitignore

@@ -0,0 +1,63 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Build output
+dist/
+build/
+*.tsbuildinfo
+
+# Environment (NIEMALS committen!)
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker volumes (lokal)
+docker-data/
+postgres-data/
+redis-data/
+media-uploads/
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# Test coverage
+coverage/
+
+# Prisma
+packages/core-service/prisma/*.db
+packages/core-service/prisma/*.db-journal
+
+# Generated Prisma Client
+packages/core-service/node_modules/.prisma/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# Certificates (generierte Zertifikate, nicht die CA-Config)
+config/step-ca/secrets/
+config/step-ca/db/
+*.pem
+*.key
+*.crt
+!config/step-ca/*.example
+
+# Backup files
+*.bak
+*.backup

.keys/deploy_ed25519

@@ -0,0 +1,7 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
+QyNTUxOQAAACDLk6asy8o6kyAzCeG8BBOKNiXhx94pi/jXoqXrgX4k6AAAAKBprr69aa6+
+vQAAAAtzc2gtZWQyNTUxOQAAACDLk6asy8o6kyAzCeG8BBOKNiXhx94pi/jXoqXrgX4k6A
+AAAECki73xblIq6Dx917rd90A5YrQwWVvp4RBMkU+RHsxNncuTpqzLyjqTIDMJ4bwEE4o2
+JeHH3imL+NeipeuBfiToAAAAGWluc2lnaHQtZGVwbG95QHhpbmlvbi5sYW4BAgME
+-----END OPENSSH PRIVATE KEY-----

.keys/deploy_ed25519.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMuTpqzLyjqTIDMJ4bwEE4o2JeHH3imL+NeipeuBfiTo insight-deploy@xinion.lan

README.md

@@ -1,2 +1,206 @@
-# INSIGHT-MVP
+# INSIGHT MVP
 
+Erweiterbare, mandantenfaehige SaaS-Business-Plattform der Xinion IT GmbH.
+
+---
+
+## Inhaltsverzeichnis
+
+- [Projektuebersicht](#projektuebersicht)
+- [Voraussetzungen](#voraussetzungen)
+- [Setup (Entwicklungsumgebung)](#setup-entwicklungsumgebung)
+- [Services & Ports](#services--ports)
+- [Projektstruktur](#projektstruktur)
+- [Branching & Commits](#branching--commits)
+- [Dokumentation](#dokumentation)
+
+---
+
+## Projektuebersicht
+
+INSIGHT ist eine Infrastruktur-Shell, auf die fachliche Module (erstes Modul: CRM) als isolierte Docker-Container aufgesetzt werden. Das System ist Cloud-Native und Kubernetes-ready.
+
+**Kernprinzipien:**
+- Zero-Trust (mTLS intern)
+- Stateless Backend-Services
+- Separate Datenbank pro Mandant (Tenant-Isolation)
+- Provider-Modell fuer Authentifizierung (lokal + MS SSO)
+
+**Tech Stack:**
+TypeScript | NestJS | React + Vite | PostgreSQL | Prisma | Redis | Traefik | Docker
+
+---
+
+## Voraussetzungen
+
+### Fuer lokale Entwicklung (MacBook)
+- Git mit SSH-Zugang zu `git.xinion.lan`
+- Docker Desktop oder Docker Engine
+- Node.js >= 20 LTS
+- npm oder yarn
+
+### Fuer den Server (ProxmoxVE VM)
+- Ubuntu 24.04 LTS
+- Docker Engine + Compose Plugin (kein Docker Desktop)
+- SSH-Key aus `.keys/deploy_ed25519.pub` im `authorized_keys` des `deploy`-Users
+
+---
+
+## Setup (Entwicklungsumgebung)
+
+### 1. Repository klonen
+```bash
+git clone ssh://git@git.xinion.lan/gitadmin/INSIGHT-MVP.git
+cd INSIGHT-MVP
+```
+
+### 2. Environment konfigurieren
+```bash
+cp .env.example .env
+# .env oeffnen und alle Werte befuellen (Passwoerter, Keys, etc.)
+```
+
+### 3. JWT-Schluessel generieren
+```bash
+# RS256 Schluessel fuer JWT-Signierung
+mkdir -p packages/core-service/keys
+openssl genpkey -algorithm RSA -out packages/core-service/keys/jwt-private.pem -pkeyopt rsa_keygen_bits:2048
+openssl rsa -pubout -in packages/core-service/keys/jwt-private.pem -out packages/core-service/keys/jwt-public.pem
+```
+
+### 4. Services starten
+```bash
+# Basis-Services
+docker compose up -d
+
+# Mit Observability-Stack
+docker compose -f docker-compose.yml -f docker-compose.observability.yml up -d
+```
+
+### 5. Datenbank-Migration
+```bash
+# Core-Schema
+docker compose exec core npx prisma migrate deploy --schema=./prisma/core.schema.prisma
+
+# Tenant-Schema (wird beim Onboarding automatisch ausgefuehrt)
+```
+
+### 6. Health-Checks pruefen
+```bash
+curl http://localhost:3000/health     # Core-Service
+curl http://localhost:8080            # Frontend
+```
+
+### 7. Erster Login
+- URL: https://insight-dev.xinion.lan (oder http://localhost)
+- Initialer Admin-Account wird beim ersten Start via Seed-Script angelegt
+
+---
+
+## Services & Ports
+
+| Service       | Port (intern) | URL (extern via Traefik)         | Beschreibung           |
+|---------------|---------------|----------------------------------|------------------------|
+| Traefik       | 80/443        | https://insight-dev.xinion.lan   | API Gateway            |
+| Core-Service  | 3000          | /api/v1/*                        | NestJS Backend         |
+| Frontend      | 8080          | /*                               | React App              |
+| PostgreSQL    | 5432          | -                                | Datenbank              |
+| PgBouncer     | 6432          | -                                | Connection Pooler      |
+| Redis         | 6379          | -                                | Cache & Event Bus      |
+| step-ca       | 9000          | -                                | Interne CA (mTLS)      |
+| Grafana       | 3001          | SSH-Tunnel                       | Monitoring Dashboards  |
+
+---
+
+## Projektstruktur
+
+```
+INSIGHT-MVP/
+  docker-compose.yml                 # Basis-Services
+  docker-compose.observability.yml   # Monitoring-Stack
+  .env.example                       # Alle Umgebungsvariablen (keine Werte!)
+  .gitignore
+  README.md                          # <- Du bist hier
+
+  .keys/                             # SSH Deployment Keys
+    deploy_ed25519
+    deploy_ed25519.pub
+
+  docs/                              # Projektdokumentation
+    INFRASTRUCTURE.md                # Server & VM Konfiguration
+    ACCESS.md                        # Zugangsdaten & SSH-Infos
+
+  packages/
+    core-service/                    # NestJS Backend
+      src/
+        core/
+          auth/                      # Auth-Service (Provider-Modell)
+          users/                     # User-Verwaltung
+          tenants/                   # Tenant-Verwaltung
+          modules/                   # Module-Registry
+        common/
+          guards/                    # JwtGuard, RolesGuard, ScopeGuard
+          decorators/                # @Public(), @Roles(), @RequireScope()
+          filters/                   # GlobalExceptionFilter
+          interceptors/              # Logging, Response-Transformation
+        config/                      # Env-Validierung (class-validator)
+        prisma/                      # PrismaService + TenantPrismaService
+      prisma/
+        core.schema.prisma           # platform_core Tabellen
+        tenant.schema.prisma         # Tenant-DB Tabellen
+
+    frontend/                        # React + Vite
+      src/
+        shell/                       # App-Shell (Layout, Routing)
+        auth/                        # Login, 2FA, Token-Management
+        admin/                       # Admin-Bereich
+        components/                  # Shared UI-Komponenten
+
+  config/                            # Service-Konfigurationen
+    traefik/
+    prometheus/
+    step-ca/
+
+  .forgejo/
+    workflows/                       # CI/CD Pipelines
+      ci.yml
+      develop.yml
+      release.yml
+```
+
+---
+
+## Branching & Commits
+
+### Branching-Strategie: GitFlow
+
+| Branch       | Zweck                                    |
+|------------- |------------------------------------------|
+| `main`       | Produktion (nur via Merge, geschuetzt)   |
+| `develop`    | Integration (nur via Merge, geschuetzt)  |
+| `feature/*`  | Neue Features                            |
+| `fix/*`      | Bugfixes                                 |
+| `hotfix/*`   | Kritische Fixes auf main                 |
+
+### Commit-Format: Conventional Commits
+```
+feat: Neues Feature
+fix: Bugfix
+chore: Tooling, Dependencies
+docs: Dokumentation
+refactor: Refactoring ohne Funktionsaenderung
+```
+
+---
+
+## Dokumentation
+
+| Dokument                        | Beschreibung                              |
+|---------------------------------|-------------------------------------------|
+| `README.md`                     | Dieses Dokument (Onboarding)              |
+| `docs/INFRASTRUCTURE.md`        | Server-Infrastruktur & VM-Setup           |
+| `docs/ACCESS.md`                | Zugangsdaten & SSH-Verbindungen           |
+| `INSIGHT_Konzept_v1.0.docx`     | Vollstaendiges Konzeptdokument (23 Kap.)  |
+| `CLAUDE_BRIEFING.docx`          | Entwickler-Briefing (Kurzreferenz)        |
+| `Summarize.md`                  | Aenderungsprotokoll (aktueller Stand)     |
+| `RUNBOOK.md`                    | Disaster Recovery Anleitung (folgt)       |

Summarize.md

@@ -0,0 +1,66 @@
+# INSIGHT MVP - Aenderungsprotokoll
+
+## Stand: 2026-03-08
+
+### Aktueller Sprint: Sprint 1 (Alpha)
+
+---
+
+### Aenderungen in dieser Session
+
+#### Projektinitialisierung & Infrastruktur-Definition
+
+**Was wurde gemacht:**
+
+1. **SSH Deployment Key erstellt**
+   - Ed25519-Schluessel unter `.keys/deploy_ed25519` generiert
+   - Public Key muss auf dem Entwicklungsserver und in Forgejo hinterlegt werden
+   - Key-Kommentar: `insight-deploy@xinion.lan`
+
+2. **Infrastruktur-Definition erstellt** (`docs/INFRASTRUCTURE.md`)
+   - ProxmoxVE VM-Spezifikation: Ubuntu 24.04 LTS, 4 vCPU, 8 GB RAM, 60 GB SSD
+   - Docker-Netzwerk-Architektur mit 3 isolierten Netzwerken
+   - Komplette Service-Landschaft definiert (Traefik, Core, Frontend, PostgreSQL, PgBouncer, Redis, step-ca)
+   - Observability-Stack definiert (Prometheus, Grafana, Loki, Tempo, Promtail, cAdvisor)
+   - Schritt-fuer-Schritt VM-Setup Anleitung
+
+3. **Zugangsdaten-Dokument erstellt** (`docs/ACCESS.md`)
+   - Git Repository Zugangsdaten
+   - SSH-Key Dokumentation und Verwendung
+   - Server-Zugangsdaten (Platzhalter fuer IP)
+   - Alle Service-Ports dokumentiert
+   - Deployment-Pfad dokumentiert
+   - Wichtige Befehle (MacBook & Server)
+
+4. **Projektstruktur aufgesetzt**
+   - Verzeichnisstruktur gemaess Briefing angelegt
+   - packages/core-service/ (NestJS Backend)
+   - packages/frontend/ (React + Vite)
+   - config/ (Traefik, Prometheus, step-ca)
+   - .forgejo/workflows/ (CI/CD)
+
+5. **Basis-Konfigurationsdateien erstellt**
+   - `.gitignore` - alle relevanten Ausschluesse
+   - `.env.example` - alle Umgebungsvariablen dokumentiert (ohne Werte)
+   - `README.md` - vollstaendiges Onboarding-Dokument
+
+---
+
+### Naechste Schritte
+
+- [ ] VM in ProxmoxVE erstellen und konfigurieren
+- [ ] SSH Deploy Key auf Server und in Forgejo hinterlegen
+- [ ] `docker-compose.yml` erstellen (alle Basis-Services)
+- [ ] `docker-compose.observability.yml` erstellen
+- [ ] NestJS Core-Service implementieren (Auth, Users, Tenants)
+- [ ] Prisma-Schemas erstellen (core + tenant)
+- [ ] React Frontend-Shell implementieren
+- [ ] CI/CD Pipelines in Forgejo Actions definieren
+
+---
+
+### Offene Fragen / Abhaengigkeiten
+
+- Server-IP wird erst bei VM-Erstellung vergeben
+- DNS-Eintraege (insight-dev.xinion.lan) muessen konfiguriert werden
+- Forgejo Deploy Key muss manuell hinterlegt werden

docs/ACCESS.md

@@ -0,0 +1,202 @@
+# INSIGHT MVP - Zugangsdaten & Server-Zugriff
+
+> **Dieses Dokument wird laufend aktualisiert und enthaelt alle relevanten
+> Zugangsinformationen fuer das Projekt.**
+
+---
+
+## 1. Git Repository
+
+| Parameter        | Wert                                                |
+|------------------|-----------------------------------------------------|
+| Git-Server       | Forgejo (self-hosted)                                |
+| URL              | `git.xinion.lan`                                    |
+| Repository (SSH) | `ssh://git@git.xinion.lan/gitadmin/INSIGHT-MVP.git` |
+| Repository (HTTP)| `https://git.xinion.lan/gitadmin/INSIGHT-MVP`       |
+| Organisation     | `gitadmin`                                          |
+| Zugriff          | SSH Key-basiert                                     |
+| CI/CD            | Forgejo Actions (GitHub Actions kompatibel)         |
+| Container Registry | `git.xinion.lan` (Forgejo built-in)               |
+
+---
+
+## 2. SSH Deployment Key
+
+Der Deployment Key liegt im Repository unter `.keys/`:
+
+| Datei                        | Beschreibung          |
+|------------------------------|-----------------------|
+| `.keys/deploy_ed25519`       | Private Key (Ed25519) |
+| `.keys/deploy_ed25519.pub`   | Public Key            |
+
+### Public Key (zur Hinterlegung auf Servern)
+```
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMuTpqzLyjqTIDMJ4bwEE4o2JeHH3imL+NeipeuBfiTo insight-deploy@xinion.lan
+```
+
+### SSH-Verbindung zum Server
+```bash
+# Verbindung zum Entwicklungsserver:
+ssh -i .keys/deploy_ed25519 deploy@<SERVER-IP>
+
+# Mit SSH-Config (empfohlen):
+# Eintrag in ~/.ssh/config:
+Host insight-dev
+    HostName <SERVER-IP>
+    User deploy
+    IdentityFile ~/git.xinion.lan/INSIGHT-MVP/.keys/deploy_ed25519
+    StrictHostKeyChecking accept-new
+```
+
+### Wo der Public Key hinterlegt werden muss
+1. **Entwicklungsserver (VM)**: `/home/deploy/.ssh/authorized_keys`
+2. **Forgejo**: Repository Settings > Deploy Keys (fuer CI/CD)
+
+---
+
+## 3. Entwicklungsserver (ProxmoxVE VM)
+
+| Parameter        | Wert                                    |
+|------------------|-----------------------------------------|
+| **Hostname**     | `insight-dev-01`                        |
+| **OS**           | Ubuntu 24.04 LTS                        |
+| **IP**           | _wird bei VM-Erstellung vergeben_       |
+| **SSH-Port**     | 22                                      |
+| **SSH-User**     | `deploy`                                |
+| **SSH-Key**      | `.keys/deploy_ed25519`                  |
+| **Docker**       | Docker Engine + Compose Plugin          |
+| **Projekt-Pfad** | `/home/deploy/insight/`                 |
+
+### Schnellzugriff nach VM-Setup
+```bash
+# SSH auf den Server
+ssh -i .keys/deploy_ed25519 deploy@<SERVER-IP>
+
+# Status aller Container pruefen
+docker compose ps
+
+# Logs eines Services
+docker compose logs -f core
+
+# Neustart aller Services
+docker compose restart
+
+# Nur Backend neustarten
+docker compose restart core
+```
+
+---
+
+## 4. Service-Ports (auf der VM)
+
+| Service         | Interner Port | Externer Port | URL                              |
+|-----------------|---------------|---------------|----------------------------------|
+| Traefik (HTTP)  | 80            | 80            | http://insight-dev.xinion.lan    |
+| Traefik (HTTPS) | 443           | 443           | https://insight-dev.xinion.lan   |
+| Traefik Dashboard | 8080        | -             | Nur intern                       |
+| Core-Service    | 3000          | -             | Via Traefik: /api/v1/*           |
+| Frontend        | 8080          | -             | Via Traefik: /*                  |
+| PostgreSQL      | 5432          | -             | Nur intern (Docker-Netzwerk)     |
+| PgBouncer       | 6432          | -             | Nur intern (Docker-Netzwerk)     |
+| Redis           | 6379          | -             | Nur intern (Docker-Netzwerk)     |
+| step-ca         | 9000          | -             | Nur intern (Docker-Netzwerk)     |
+
+### Observability (nur intern, kein oeffentlicher Zugriff)
+
+| Service         | Port  | Zugriff                          |
+|-----------------|-------|----------------------------------|
+| Grafana         | 3001  | SSH-Tunnel: `ssh -L 3001:localhost:3001 deploy@<IP>` |
+| Prometheus      | 9090  | Nur intern                       |
+| Loki            | 3100  | Nur intern                       |
+| Tempo           | 3200  | Nur intern                       |
+
+---
+
+## 5. Datenbank-Zugangsdaten
+
+> **Echte Passwoerter stehen in der `.env`-Datei auf dem Server.
+> Niemals in Git committen!**
+
+| Parameter         | Wert (Platzhalter)              |
+|-------------------|---------------------------------|
+| DB-Host           | `pgbouncer` (via Docker-Netzwerk) |
+| DB-Port           | `6432`                          |
+| Core-DB-Name      | `platform_core`                 |
+| Tenant-DB-Schema  | `tenant_{slug}`                 |
+| DB-User           | Siehe `.env` -> `DB_USER`       |
+| DB-Passwort       | Siehe `.env` -> `DB_PASSWORD`   |
+
+---
+
+## 6. Container Registry
+
+| Parameter        | Wert                                                |
+|------------------|-----------------------------------------------------|
+| Registry-URL     | `git.xinion.lan`                                    |
+| Image-Prefix     | `git.xinion.lan/gitadmin/insight-{service}`         |
+| Authentifizierung| Forgejo Login-Credentials                           |
+
+### Image-Namen
+```
+git.xinion.lan/gitadmin/insight-core:latest
+git.xinion.lan/gitadmin/insight-core:develop
+git.xinion.lan/gitadmin/insight-core:v0.1.0
+git.xinion.lan/gitadmin/insight-frontend:latest
+```
+
+---
+
+## 7. Deployment-Pfad
+
+```
+MacBook (Entwicklung)
+    |
+    | git push
+    v
+Forgejo (git.xinion.lan)
+    |
+    | Forgejo Actions CI/CD
+    | - Lint, Type-Check, Tests, Build
+    | - Docker Image bauen & pushen
+    v
+Server (insight-dev-01)
+    |
+    | docker compose pull && docker compose up -d
+    v
+Laufende Anwendung
+```
+
+---
+
+## 8. Wichtige Befehle
+
+### Vom MacBook aus
+```bash
+# Code pushen
+git push origin develop
+
+# SSH auf Server
+ssh -i .keys/deploy_ed25519 deploy@<SERVER-IP>
+
+# Grafana oeffnen (SSH-Tunnel)
+ssh -L 3001:localhost:3001 -i .keys/deploy_ed25519 deploy@<SERVER-IP>
+# Dann im Browser: http://localhost:3001
+```
+
+### Auf dem Server
+```bash
+# Alle Services starten
+docker compose up -d
+
+# Mit Observability
+docker compose -f docker-compose.yml -f docker-compose.observability.yml up -d
+
+# Health-Check
+curl http://localhost:3000/health
+
+# Datenbank-Migration
+docker compose exec core npx prisma migrate deploy
+
+# Logs folgen
+docker compose logs -f --tail=100
+```

docs/INFRASTRUCTURE.md

@@ -0,0 +1,257 @@
+# INSIGHT MVP - Infrastruktur-Definition
+
+## 1. Uebersicht
+
+Die gesamte INSIGHT-Plattform laeuft auf einer ProxmoxVE-VM im internen Netzwerk.
+Alle Services werden als Docker-Container betrieben.
+
+---
+
+## 2. VM-Konfiguration (ProxmoxVE)
+
+| Komponente      | Spezifikation                          |
+|-----------------|----------------------------------------|
+| **Hostname**    | `insight-dev-01`                       |
+| **OS**          | Ubuntu 24.04 LTS (Server)              |
+| **CPU**         | 4 vCPUs                                |
+| **RAM**         | 8 GB (16 GB empfohlen)                 |
+| **Storage**     | 60 GB SSD                              |
+| **Netzwerk**    | Feste interne IP (wird bei Setup vergeben) |
+| **SSH-Zugang**  | Key-basiert (Ed25519), kein Passwort-Login |
+| **User**        | `deploy` (non-root, Mitglied der `docker`-Gruppe) |
+
+### Betriebssystem-Hardening
+
+- SSH: nur Key-basiert (`PasswordAuthentication no`)
+- Firewall (ufw):
+  - Port 22 (SSH) - nur internes Netzwerk
+  - Port 80 (HTTP -> Redirect auf HTTPS)
+  - Port 443 (HTTPS)
+  - Alle anderen Ports: DENY
+- Automatische Sicherheitsupdates: `unattended-upgrades` aktiviert
+- Fail2ban fuer SSH-Brute-Force-Schutz
+
+---
+
+## 3. Software auf der VM
+
+| Software            | Version     | Installationsmethode           |
+|---------------------|-------------|--------------------------------|
+| Docker Engine       | >= 27.x     | Official Docker APT Repository |
+| Docker Compose      | Plugin      | Mitgeliefert mit Docker Engine |
+| Git                 | >= 2.x      | APT                            |
+| ufw                 | Aktuell     | APT (vorinstalliert)           |
+| fail2ban            | Aktuell     | APT                            |
+| unattended-upgrades | Aktuell     | APT (vorinstalliert)           |
+
+**Kein** Docker Desktop, kein Node.js, kein npm auf der VM.
+Alles laeuft in Containern.
+
+---
+
+## 4. Docker-Netzwerk-Architektur
+
+```
+                    Internet / Internes Netz
+                            |
+                      [ Port 80/443 ]
+                            |
+                    +-------v--------+
+                    |    Traefik     |  API Gateway, SSL-Terminierung,
+                    |   (Gateway)    |  Rate Limiting, mTLS-Terminierung
+                    +---+-------+----+
+                        |       |
+              +---------+       +---------+
+              |                           |
+      +-------v--------+         +-------v--------+
+      |  Core-Service   |         |    Frontend    |
+      |    (NestJS)     |         |  (React/Vite)  |
+      |   Port: 3000    |         |  Port: 8080    |
+      +---+--------+----+         +----------------+
+          |        |
+    +-----v--+  +--v------+
+    |  Redis  |  | PgBouncer|
+    |  :6379  |  |  :6432   |
+    +----+----+  +----+-----+
+         |            |
+         |       +----v------+
+         |       | PostgreSQL |
+         |       |   :5432    |
+         +-------+------------+
+```
+
+### Docker-Netzwerke
+
+| Netzwerk      | Zweck                                           |
+|---------------|-------------------------------------------------|
+| `insight-web` | Traefik <-> Core-Service, Frontend (extern erreichbar) |
+| `insight-db`  | Core-Service <-> PgBouncer <-> PostgreSQL (intern) |
+| `insight-cache`| Core-Service <-> Redis (intern)                 |
+
+### mTLS (step-ca)
+
+Alle interne Kommunikation zwischen Containern wird ueber mTLS abgesichert.
+step-ca (Smallstep) fungiert als interne Certificate Authority.
+
+| Komponente    | Zertifikat                    |
+|---------------|-------------------------------|
+| Traefik       | Wildcard fuer externe Domain  |
+| Core-Service  | `core-service.insight.local`  |
+| Frontend      | `frontend.insight.local`      |
+| PostgreSQL    | `postgres.insight.local`      |
+| Redis         | `redis.insight.local`         |
+| PgBouncer     | `pgbouncer.insight.local`     |
+
+---
+
+## 5. Container-Services (docker-compose.yml)
+
+| Service       | Image                          | Port (intern) | Port (extern) | Beschreibung                  |
+|---------------|--------------------------------|---------------|---------------|-------------------------------|
+| `traefik`     | traefik:3                      | 80, 443, 8080 | 80, 443       | API Gateway, Reverse Proxy    |
+| `core`        | insight-core:latest            | 3000          | -             | NestJS Backend                |
+| `frontend`    | insight-frontend:latest        | 8080          | -             | React App (Nginx served)      |
+| `postgres`    | postgres:16-alpine             | 5432          | -             | Datenbank                     |
+| `pgbouncer`   | edoburu/pgbouncer:latest       | 6432          | -             | Connection Pooler             |
+| `redis`       | redis:7-alpine                 | 6379          | -             | Cache, Sessions, Event Bus    |
+| `step-ca`     | smallstep/step-ca:latest       | 9000          | -             | Interne Certificate Authority |
+
+---
+
+## 6. Observability-Stack (docker-compose.observability.yml)
+
+| Service          | Image                           | Port (intern) | Beschreibung               |
+|------------------|---------------------------------|---------------|-----------------------------|
+| `prometheus`     | prom/prometheus:latest          | 9090          | Metrics-Storage             |
+| `grafana`        | grafana/grafana:latest          | 3001          | Dashboards & Alerting       |
+| `loki`           | grafana/loki:latest             | 3100          | Log-Storage                 |
+| `tempo`          | grafana/tempo:latest            | 3200, 4317    | Tracing-Backend             |
+| `promtail`       | grafana/promtail:latest         | -             | Log-Collector               |
+| `cadvisor`       | gcr.io/cadvisor/cadvisor:latest | 8081          | Container-Metrics           |
+| `postgres-exp`   | prometheuscommunity/postgres-exporter | 9187    | DB-Metrics                  |
+
+**Grafana ist NICHT oeffentlich erreichbar** - nur ueber SSH-Tunnel oder internes Netz.
+
+---
+
+## 7. Datenbank-Struktur
+
+```
+PostgreSQL-Server
+  platform_core            <- Einmalig: Tenants, Users, Roles, Modules, Help
+  tenant_{slug}            <- Pro Mandant (z.B. tenant_acme_corp)
+```
+
+| Datenbank       | Zweck                                              |
+|-----------------|-----------------------------------------------------|
+| `platform_core` | Plattform-Verwaltung (Users, Tenants, Roles, Modules) |
+| `tenant_{slug}` | Mandant-Daten (Profile, Stammdaten, Moduldaten)      |
+
+---
+
+## 8. DNS / Domains
+
+| Eintrag                    | Ziel              | Zweck                          |
+|----------------------------|--------------------|-------------------------------|
+| `insight-dev.xinion.lan`   | VM-IP              | Entwicklungs-Frontend          |
+| `api.insight-dev.xinion.lan` | VM-IP            | API-Endpunkt                   |
+| `git.xinion.lan`           | Forgejo-Server     | Git Repository & CI/CD         |
+
+---
+
+## 9. Backup (Alpha/Dev)
+
+| Was                  | Wohin                                  | Frequenz  |
+|----------------------|----------------------------------------|-----------|
+| PostgreSQL (alle DBs)| Separates ProxmoxVE Volume             | Taeglich  |
+| Media-Dateien        | Separates ProxmoxVE Volume             | Taeglich  |
+| Konfiguration        | Git Repository (ohne .env)             | Per Commit|
+
+---
+
+## 10. VM-Setup Anleitung (Schritt fuer Schritt)
+
+### 10.1 VM in ProxmoxVE erstellen
+```bash
+# ProxmoxVE Web-UI oder CLI:
+# - Template: Ubuntu 24.04 LTS Cloud-Init
+# - CPU: 4 Cores
+# - RAM: 8192 MB
+# - Disk: 60 GB (SCSI, SSD-backed)
+# - Network: vmbr0, DHCP oder feste IP
+```
+
+### 10.2 Basis-Setup nach Erstinstallation
+```bash
+# System aktualisieren
+sudo apt update && sudo apt upgrade -y
+
+# Deploy-User anlegen
+sudo adduser --disabled-password deploy
+sudo usermod -aG sudo deploy
+
+# SSH-Key fuer Deploy-User hinterlegen
+sudo mkdir -p /home/deploy/.ssh
+sudo cp /path/to/deploy_ed25519.pub /home/deploy/.ssh/authorized_keys
+sudo chown -R deploy:deploy /home/deploy/.ssh
+sudo chmod 700 /home/deploy/.ssh
+sudo chmod 600 /home/deploy/.ssh/authorized_keys
+
+# SSH haerten
+sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
+sudo sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
+sudo systemctl restart sshd
+```
+
+### 10.3 Firewall
+```bash
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+sudo ufw allow 22/tcp    # SSH
+sudo ufw allow 80/tcp    # HTTP
+sudo ufw allow 443/tcp   # HTTPS
+sudo ufw enable
+```
+
+### 10.4 Docker installieren
+```bash
+# Docker Official GPG Key
+sudo apt install -y ca-certificates curl
+sudo install -m 0755 -d /etc/apt/keyrings
+sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
+  -o /etc/apt/keyrings/docker.asc
+sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+# Docker Repo hinzufuegen
+echo "deb [arch=$(dpkg --print-architecture) \
+  signed-by=/etc/apt/keyrings/docker.asc] \
+  https://download.docker.com/linux/ubuntu \
+  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
+  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+# Docker installieren
+sudo apt update
+sudo apt install -y docker-ce docker-ce-cli containerd.io \
+  docker-buildx-plugin docker-compose-plugin
+
+# Deploy-User zur docker-Gruppe
+sudo usermod -aG docker deploy
+```
+
+### 10.5 Fail2ban
+```bash
+sudo apt install -y fail2ban
+sudo systemctl enable fail2ban
+sudo systemctl start fail2ban
+```
+
+### 10.6 Projekt deployen
+```bash
+# Als deploy-User:
+su - deploy
+git clone git@git.xinion.lan:gitadmin/INSIGHT-MVP.git ~/insight
+cd ~/insight
+cp .env.example .env
+# .env befuellen mit echten Werten
+docker compose up -d
+```