Built for Developers

Tech Stack

Modern, type-safe und enterprise-grade. Die Architektur hinter flowgeist – transparent dokumentiert für Entwickler und IT-Verantwortliche.

Technologien

Jede Schicht gewählt für Skalierbarkeit, Wartbarkeit und Developer Experience

Frontend

Single-Page-Application mit SSR-Fähigkeit, component-basiert und vollständig typisiert.

  • React 19 – UI-Framework
  • Next.js 15 – App Router, SSR/SSG
  • TypeScript 5.7 – 100% type-safe
  • Tailwind CSS 4 – Utility-First Styling
  • shadcn/ui – Radix-basierte Komponenten
  • TanStack Query – Server State Management
  • Zod – Runtime-Validierung

Backend

Modularer Monolith mit strikter Modul-Isolation. API-First, decorator-basiert, NestJS-Patterns.

  • NestJS 11 – Dependency Injection, Module
  • TypeScript 5.7 – Strict Mode, Path-Aliases
  • Prisma ORM 6 – Type-safe Database Access
  • Zod – DTO-Validierung
  • Passport JWT – Auth mit Refresh-Token-Rotation
  • Helmet – HTTP-Security-Headers
  • Bull/BullMQ – Background Jobs (geplant)

Datenbank & Storage

PostgreSQL als Single Source of Truth. Type-safe ORM mit versionierten Migrationen.

  • PostgreSQL 16 – Primary Database
  • Prisma Migrate – Versionierte DB-Migrationen
  • Redis 7 – Caching & Rate Limiting
  • pgvector – Vector Search (geplant)

Infrastructure

Containerisiert auf deutscher Cloud-Infrastruktur. Kein Vendor-Lock-in.

  • Docker – Multi-Stage Builds
  • Docker Compose – Orchestrierung
  • Nginx – Reverse Proxy & SSL
  • Hetzner Cloud – Frankfurt, Deutschland
  • Let's Encrypt – Automated TLS
  • Ansible – Infrastructure as Code

CI/CD & Tooling

Vollständig automatisiertes Release-Management mit Semantic Versioning.

  • GitHub Actions – CI/CD Pipelines
  • release-please – Automated Versioning
  • pnpm Workspaces – Monorepo-Management
  • ESLint + Prettier – Code-Quality
  • Vitest – Unit Testing
  • Playwright – E2E Testing

Monitoring & Analytics

Privacy-first Analytics und strukturiertes Logging ohne PII.

  • Umami Analytics – DSGVO-konform, cookieless
  • NestJS Logger – Strukturiertes Logging
  • Postmark – Transactional Email
  • Sentry-ready – Error Tracking (geplant)

Architektur

Multi-Tenant SaaS mit strikter Modul-Isolation

Client
React SPA – Next.js App Router, Tenant-spezifische Subdomains (*.flowgeist.de)
↓ HTTPS
Edge
Nginx Reverse Proxy – TLS-Terminierung, Subdomain-Routing, Static Files, Rate Limiting
↓ :3050 / :3150
API
NestJS Application – JWT-Auth, Tenant-Resolution via Header, Modul-Isolation (keine Cross-Modul-Imports)
↓ Prisma ORM
Data
PostgreSQL 16 + Redis 7 – Tenant-Isolation auf Row-Level (Tenant-ID pro Datensatz)
↓ SMTP / API
External
Postmark (Email), Lexware API (ERP-Integration)

Security & Compliance

ISO 27001-konforme Architektur – Security by Design

JWT + Refresh-Rotation
Stateless Auth mit automatischer Token-Erneuerung
Tenant-Isolation
Row-Level Separation, keine Cross-Tenant-Queries
XSS-Sanitization
Alle User-Inputs werden serverseitig escaped
Audit-Logs
Revisionssichere Protokollierung aller kritischen Aktionen
DSGVO-konform
Datenverarbeitung ausschließlich in Deutschland
Modul-Isolation
Keine direkten Cross-Modul-Imports, API-First-Kommunikation
Helmet Headers
CSP, HSTS, X-Frame-Options, X-Content-Type-Options
Secret Management
Keine Secrets im Code, Environment-basiert

DevOps & Release-Management

Automatisiertes Deployment mit Semantic Versioning

Monorepo-Struktur

pnpm Workspaces mit drei Paketen:

apps/api – NestJS Backend
apps/web – Next.js Frontend
packages/shared – Shared Types & Utils

Strikte Modul-Isolation: Jedes Feature lebt in modules/[name]/ mit eigenen Routes, DTOs und Services.

Release-Please

Automatisches Versioning via Conventional Commits:

feat: → Minor Bump
fix: → Patch Bump
feat!: → Major Bump

CHANGELOG.md wird automatisch gepflegt. Release-PRs generieren Version-Tags für apps/api und apps/web unabhängig.

Deployment-Pipeline

GitHub Actions mit SSH-Deploy auf Hetzner:

docker compose build
docker compose up -d
nginx -t && systemctl reload nginx

Zero-Downtime-Deploy durch Health-Checks und Rolling Restarts. Rollback via Docker-Image-Tags.

flowgeist in Zahlen

Architektur-Metriken, die für sich sprechen

100%
TypeScript
3
Monorepo Packages
10+
API-Module
0
Cross-Modul-Imports
DE
Hosting-Lokation

Häufige Fragen

Technische Details für Entwickler und IT-Verantwortliche

Wie ist die Multi-Tenancy-Architektur umgesetzt?

Jeder Tenant erhält eine eigene Subdomain ([tenant].flowgeist.de). Nginx extrahiert die Subdomain und setzt den X-Tenant-Slug Header. NestJS resolved den Tenant im Request-Pipeline und isoliert alle DB-Queries auf Row-Level via Tenant-ID. Reserved Slugs (api, app, www, admin) werden blockiert.

Wie funktioniert die Modul-Isolation?

Jedes Feature-Modul lebt in apps/api/src/modules/[name]/ mit eigenen Controllern, Services, DTOs und Prisma-Modellen. Direkte Imports zwischen Modulen sind verboten – Kommunikation erfolgt ausschließlich über definierte API-Endpoints. Ein automatisierter Compliance-Check validiert diese Isolation.

Wie werden Datenbank-Migrationen gehandhabt?

Prisma Migrate verwaltet versionierte SQL-Migrationen. Schema-Änderungen werden in schema.prisma vorgenommen, dann mit prisma migrate dev generiert. In Production läuft prisma migrate deploy beim Deployment. Migrationen sind in Git versioniert.

Welche Node.js-Version wird eingesetzt?

Node.js 22 LTS (Jod). Die Version ist in .nvmrc und Dockerfile.api fixiert. pnpm als Package Manager (v9+), definiert in pnpm-workspace.yaml.

Gibt es eine API-Dokumentation?

Ja. NestJS generiert automatisch OpenAPI/Swagger-Doku unter /api/docs. Alle Endpoints sind mit @ApiOperation und @ApiResponse annotiert. DTOs nutzen Zod für Runtime-Validierung und generieren Swagger-Schemas.

Wie sieht der Testing-Ansatz aus?

Vitest für Unit-Tests (Services, Utils), Playwright für E2E-Tests (apps/e2e). E2E-Tests laufen gegen echte Docker-Container mit isolierter PostgreSQL-Instanz. CI-Pipeline in GitHub Actions führt Tests bei jedem PR aus.