ADR-001: Technology Stack

Status: ✅ Accepted — 2026-07-03

Entscheidung: Cartly Tech Stack für Phase 1 (MVP)

Kontext

Cartly ist eine AI-native ERP+POS SaaS-Plattform für Fashion-Einzelhändler (1–5 Filialen) im DACH-Raum. Wir benötigen einen Tech Stack, der:

Schnelle Entwicklung ermöglicht (Startup/MVP-Kontext)
Horizontale Skalierung für Multi-Tenant unterstützt
PWA-Fähig ist (Browser-basiert, keine Desktop-Clients)
AI-Features über OpenRouter integrierbar macht
DSGVO-konform ist

Entscheidung

Gewählter Stack: React + Fastify (TypeScript Full-Stack)

Technology Stack Table

Layer	Technology	Rationale
Frontend	React 18 + TypeScript + Vite	TypeScript全程强 Typisierung, Vite = schnell Builds, exzellentes PWA-Ökosystem (Workbox)
UI-Komponenten	Radix UI + Tailwind CSS	Accessible Components, Customizable, Fashion-Retail Brand-Ready
State Management	Zustand + TanStack Query	Leichtgewichtig, TypeScript-nativ, Server State via TanStack
Backend	Node.js + Fastify + TypeScript	Schnellster HTTP-Layer (Benchmark-Sieger), TypeScript-nativ, Plugin-Ökosystem
ORM	Prisma	Type-safe, Auto-Migrations, Multi-Tenant via tenant_id, exzellente DX
Database	PostgreSQL 16 (Supabase / Neon)	Zuverlässig, JSONB für flexible Schemata, Row-Level Security für Multi-Tenant
Cache / Session	Redis (Upstash)	Serverless-kompatibel, niedrige Latenz, Pub/Sub für Real-time
Auth	JWT (Access + Refresh) + HTTP-only Cookies	Bewährt, keine Server-Side Session nötig, GDPR-konform
File Storage	S3 (Backblaze B2 als Backup)	Günstig, skalierbar, CDN-fertig
Search	Meilisearch	Open Source, schnell, typo-tolerant, Fashion-spezifisch (Facets für Größe/Farbe)
AI	OpenRouter (einheitlicher Proxy)	Provider-agnostisch, Kostenkontrolle, Single-Endpoint
Infrastructure	Docker + Railway / Render (MVP) → EKS (Scale)	Railway = schnell deployed, keine AWS-Komplexität für MVP; Migration zu Kubernetes bei Scale
Monitoring	Sentry (Errors) + Highlight.io (Sessions)	Error Tracking + Session Replay für schnellere Debugging
CI/CD	GitHub Actions	Integriert, kostenlos für Open Source-Repos, Actions-Ökosystem

Warum nicht andere Optionen

Strapi/Shopify Headless: Zu opinionated, weniger Kontrolle über Frontend-Stack
Supabase (als Backend): Gut für MVP, aber bei komplexen Business-Logik wird es fragil
Django/Rails: Zu monolithisch, Frontend-Entscheidungen eingeschränkt
PHP/Symfony: Nicht skalierbar, schwer wartbar, Team-Suche schwierig
Next.js + API Routes: Konzeptionell möglich, aber Fastify bietet bessere Performance undFlexibilität für unseren Use Case

Konsequenzen

Positiv

TypeScript durchgängig (bessere DX, weniger Runtime-Fehler)
Fastify = schnellster Node.js HTTP-Layer (Benchmark)
Vite = extrem schnelle Builds im Development
React 18 + Workbox = exzellentes PWA-Ökosystem
Radix UI = accessible, customizable Components ohne Vendor Lock-in
Prisma = type-safe DB-Access mit Auto-Migrations
OpenRouter = AI-Provider-agnostisch (kein Vendor Lock-in auf OpenAI)

Negativ

Zwei verschiedene Sprachen (TypeScript + SQL) — akzeptabel
Python AI-Integrationen erfordern subprocess/Service-Trennung — durch OpenRouter Proxy gelöst
Tailwind CSS = Utility-First Learning Curve — lohnt sich für Customization

Änderungshistorie

Datum	Version	Änderung
2026-07-03	v1.0	Initiale Entscheidung basierend auf PRD-001 Review

Erstellt: 2026-07-03 von Documentation Agent (a66674bf)
Genehmigt: CPTO (b999c0b2) — implicit durch PRD-001 Freigabe