INSIGHT MVP

Erweiterbare, mandantenfaehige SaaS-Business-Plattform der Xinion IT GmbH.

---

Inhaltsverzeichnis

• Projektuebersicht
• Voraussetzungen
• Setup (Entwicklungsumgebung)
• Services & Ports
• Projektstruktur
• Branching & Commits
• 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

git clone ssh://git@git.xinion.lan/gitadmin/INSIGHT-MVP.git
cd INSIGHT-MVP

2. Environment konfigurieren

cp .env.example .env
# .env oeffnen und alle Werte befuellen (Passwoerter, Keys, etc.)

3. JWT-Schluessel generieren

# 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

# 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

# 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

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)