NestJS moduly

Backend je postaven na frameworku NestJS a organizován do feature modulů. Každý modul zapouzdřuje svůj controller, service, DTOs a entity.

Struktura modulu

Každý modul dodržuje následující vzor:

modules/feature/
├── feature.module.ts      # Definice modulu
├── feature.controller.ts  # HTTP endpointy
├── feature.service.ts     # Business logika
├── dto/                   # Data Transfer Objects
│   ├── create-feature.dto.ts
│   └── update-feature.dto.ts
└── entities/              # TypeORM entity
    └── feature.entity.ts

Přehled modulů

Doménové moduly

Modul	Adresář	Popis
Auth	`modules/auth/`	Autentizace (Magic Link, Google OAuth, email/password), JWT tokeny, správa session
Users	`modules/users/`	CRUD uživatelů, aktivace/deaktivace, přepínání rolí
Courses	`modules/courses/`	Správa kurzů, team matching, kanban, generování, náhrady
Bookings	`modules/bookings/`	Rezervace kurzů, potvrzení, storno, recenze
Instructors	`modules/instructors/`	Profily instruktorů, certifikace, specializace
Companies	`modules/companies/`	Firemní profily, členové, ověření

Podpůrné moduly

Modul	Adresář	Popis
Sales	`modules/sales/`	B2B CRM -- leady, aktivity, pipeline, konverze na firmy
Availability	`modules/availability/`	Správa dostupnosti instruktorů (bitmask sloty)
Regions	`modules/regions/`	14 českých krajů + 62 oblastních spolků ČČK
Payments	`modules/payments/`	Stripe platby, fakturace, refundace, PDF generátor
Notifications	`modules/notifications/`	In-app a e-mailové notifikace
Email	`modules/email/`	E-mailová služba (Resend), magic tokeny pro akce z e-mailu
Files	`modules/files/`	Nahrávání souborů přes S3/MinIO, presigned URLs
Verify	`modules/verify/`	Ověření telefonu přes Twilio SMS OTP
Geo	`modules/geo/`	H3 hexagonální grid, města, pokrytí instruktorů
ARES	`modules/ares/`	Vyhledávání v českém obchodním rejstříku (ARES)
Jobs	`modules/jobs/`	BullMQ procesory (e-maily, SMS upomínky, generování kurzů)
Admin	`modules/admin/`	Administrátorské statistiky a systémový health check
Health	`modules/health/`	Health check endpoint (`/api/v1/health`)

WebSockets

Modul	Adresář	Popis
WebSockets	`src/websockets/`	Socket.IO gateway pro real-time aktualizace

Detail klíčových modulů

Auth modul

Tři metody autentizace: Magic Link (OTP přes e-mail), Google OAuth (přes WorkOS) a klasické email/password.

Controller: auth.controller.ts -- 16 endpointů (register, login, magic-link, OAuth, refresh, me, switch-role, ...)
Service: auth.service.ts -- generování JWT, ověřování, správa cookies
Entity: magic-link.entity.ts -- OTP kódy (hashované bcrypt)
Strategie: jwt.strategy.ts -- Passport JWT strategie
DTO: unified-profile.dto.ts -- kombinovaný profil (user + instructor + company + garant)

Courses modul

Nejkomplexnější modul -- správa kurzů, týmový matching, bulk pozvánky, náhrady, kanban.

Obsahuje více controllerů:

Controller	Route prefix	Účel
`CoursesController`	`/courses`	CRUD kurzů, publikování, rušení, tým
`CourseGenerationController`	`/courses/generate`	Automatické generování kurzů
`CourseProposalsController`	`/course-proposals`	Návrhy kurzů ke schválení
`ReplacementController`	`/replacements`	Náhrady nemocných instruktorů
`WithdrawalController`	`/withdrawals`	Žádosti o odstoupení z kurzu
`GenerationLogsController`	`/generation-logs`	Logy generovacího algoritmu

Instructors modul

Profily instruktorů, certifikace a specializace.

Controller	Route prefix	Účel
`InstructorsController`	`/instructors`	CRUD instruktorů, schvalování, pozastavení
`SpecializationController`	`/specializations`	CRUD typů specializací
`InstructorSpecializationController`	`/instructors`	Přiřazení specializací instruktorům

InstructorSpecializationController sdílí route prefix /instructors s InstructorsController -- endpointy se sloučí pod stejnou base route.

Regions modul

Správa 14 českých krajů (ISO 3166-2:CZ) a 62 oblastních spolků Českého červeného kříže.

CRUD krajů a oblastních spolků
Přiřazení garantů ke krajům (GarantRegion M2M)
Statistiky za region

Sdílené komponenty (common/)

Adresář apps/api/src/common/ obsahuje sdílené části používané napříč moduly:

Adresář	Obsah
`guards/`	`JwtAuthGuard`, `RolesGuard`
`decorators/`	`@CurrentUser()`, `@Roles()`, `@Public()`
`filters/`	`HttpExceptionFilter` -- formátování chybových odpovědí
`pipes/`	Validační pipes
`dto/`	`PaginationDto`, `PaginatedResponseDto`, `SortingDto`
`entities/`	`BaseEntity` (id, createdAt, updatedAt)
`cache/`	`CacheService` -- Redis cache s mutex stampede protection
`utils/`	`h3.utils.ts` -- H3 geospatial utility

Registrace modulů

Všechny moduly jsou registrované v apps/api/src/app.module.ts:

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    TypeOrmModule.forRootAsync({ useFactory: databaseConfig }),
    BullModule.forRootAsync({ useFactory: redisConfig }),
    CacheModule,     // Globální -- dostupný všude bez importu
    AuthModule,
    UsersModule,
    CoursesModule,
    BookingsModule,
    InstructorsModule,
    CompaniesModule,
    SalesModule,
    RegionsModule,
    // ... a další
  ],
})
export class AppModule {}

BullMQ fronty (Jobs modul)

Asynchronní zpracování úloh přes Redis:

Fronta	Účel
`email`	Odesílání e-mailů přes Resend
`notifications`	In-app notifikace
`course-generation`	Automatické generování kurzů
`replacement`	Hledání náhradních instruktorů
`sms-reminders`	Denní SMS upomínky (9:00)

On this page