INSIGHT-MVP/README.md

# 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)       |