Přehled architektury

Celkový přehled architektury platformy Turtor -- stack, technologie a klíčové principy

Turtor je rezervační platforma pro školení první pomoci v České republice. Systém je postaven jako monorepo s odděleným backendem (NestJS API), dvěma frontend aplikacemi (admin dashboard a veřejný web) a sdílenými balíčky.

Technologický stack

Vrstva	Technologie
Monorepo	Turborepo + pnpm workspaces
Backend	NestJS (Node.js), TypeScript strict
Frontend	React 19, TanStack Router, TanStack Query
Databáze	PostgreSQL 16 + TypeORM
Cache & fronty	Redis 7 (caching, BullMQ job queues)
Autentizace	Magic Link + Google OAuth + email/password, JWT v HTTP-only cookies
Soubory	S3-kompatibilní úložiště (MinIO pro vývoj)
E-maily	Resend (produkce), MailHog (vývoj)
SMS	Twilio (OTP ověření, upomínky)
Platby	Stripe (karty) + fakturace (B2B)
Geolokace	H3 hexagonální grid (Uber H3)
Testy	Vitest (unit), Playwright (E2E)
Deploy	Docker Compose na Hetzner VPS

Architektura na vysoké úrovni

┌─────────────┐  ┌─────────────┐
│  Admin App  │  │   Web App   │
│  (port 3000)│  │  (port 3002)│
│  React 19   │  │  React 19   │
└──────┬──────┘  └──────┬──────┘
       │                │
       └───────┬────────┘
               │ HTTP + WebSocket
               ▼
       ┌───────────────┐
       │   NestJS API  │
       │  (port 4405)  │
       └───┬───┬───┬───┘
           │   │   │
    ┌──────┘   │   └──────┐
    ▼          ▼          ▼
┌────────┐ ┌───────┐ ┌────────┐
│Postgres│ │ Redis │ │ MinIO  │
│  :5433 │ │ :6380 │ │ :9002  │
└────────┘ └───────┘ └────────┘

Tři aplikace

Aplikace	Adresář	Port	Účel
API	`apps/api/`	4405	NestJS REST API + WebSocket gateway
Admin	`apps/admin/`	3000	Dashboard pro autentizované uživatele (správa kurzů, instruktorů, firem)
Web	`apps/web/`	3002	Veřejný web -- výpis kurzů, checkout, profil

Sdílené balíčky

Balíček	Adresář	Účel
`@turtor/api-types`	`packages/api-types/`	Orval-generované React Query hooky a Axios klient
`@turtor/shared`	`packages/shared/`	Sdílené konstanty, utility, labely, enumy
`@turtor/ui`	`packages/ui/`	shadcn/ui knihovna komponent
`@turtor/config`	`packages/config/`	ESLint a TypeScript konfigurace

Klíčové principy

Typová bezpečnost skrz celý stack

Backend definuje DTO třídy s @ApiProperty() dekorátory, ze kterých se generuje OpenAPI specifikace. Orval z ní vytváří TypeScript typy a React Query hooky -- frontend tak pracuje s přesně typovaným API bez manuálního psaní typů.

Modulární backend

NestJS API je rozděleno do feature modulů (auth, users, courses, bookings, instructors, companies, sales atd.), kde každý modul zapouzdřuje svůj controller, service, DTOs a entity.

Dva enum systémy

@turtor/shared -- TypeScript enumy s UPPERCASE klíči (CourseStatus.DRAFT), používané backendem
@turtor/api-types/models -- Orval-generované const objekty s lowercase klíči (courseStatus.draft), generované z OpenAPI

Region-aware dotazy

Admin aplikace používá globální filtr regionu přes ManageRegionContext. Hooky automaticky injektují regionId do API dotazů -- data jsou vždy filtrována podle aktuálně vybraného regionu.

Vývojové příkazy

# Spuštění všech služeb
pnpm dev

# Spuštění Docker služeb (Postgres, Redis, MinIO, MailHog)
pnpm docker:up

# Databáze
pnpm db:migrate          # Spustit migrace
pnpm db:seed demo --rich # Seed demo dat

# Typy
pnpm orval               # Přegenerovat API typy

# Kvalita kódu
pnpm lint                # Lint
pnpm typecheck           # Type check
pnpm test                # Unit testy
pnpm test:e2e            # E2E testy

Swagger dokumentace

Po spuštění API je Swagger UI dostupný na:

http://localhost:4405/docs

OpenAPI specifikace se automaticky exportuje do apps/api/openapi.json při startu dev serveru.

On this page