Backend

Entrypoint & config

File	Responsibility
`backend/src/main.ts`	Bootstraps Nest, registers middleware, builds OpenAPI 3.1, mounts SPA fallback.
`backend/src/app.module.ts`	Root module; wires every feature module + global guards/filters.
`backend/src/config/env.schema.ts`	Zod-validated env schema, `SETTINGS_KEYS`, system category metadata.

Database

File	Responsibility
`backend/src/database/database.module.ts`	TypeORM `better-sqlite3` config, entity + migration registration.
`backend/src/database/database-init.service.ts`	Initializes the DataSource, enforces WAL PRAGMA, runs migrations, verifies seed.
`backend/src/database/migrations/1700000000000-InitSchema.ts`	Creates all tables and sets WAL + foreign keys.
`backend/src/database/migrations/1700000000100-SeedSystemData.ts`	Seeds the 6 system categories and default settings.
`backend/src/database/entities/user.entity.ts`	`user` table (admin/player role, enabled/disabled status).
`backend/src/database/entities/setting.entity.ts`	`setting` key/value table.
`backend/src/database/entities/category.entity.ts`	`category` table with `system_key` unique index.
`backend/src/database/entities/challenge.entity.ts`	`challenge` table (difficulty, decay, protocol, flag, port).
`backend/src/database/entities/challenge-file.entity.ts`	`challenge_file` table for attachments.
`backend/src/database/entities/solve.entity.ts`	`solve` table with unique `(challenge_id, user_id)`.
`backend/src/database/entities/refresh-token.entity.ts`	`refresh_token` table (token_hash + revocation).
`backend/src/database/entities/blog-post.entity.ts`	`blog_post` table (draft/published + publishedAt index).

Common

File	Responsibility
`backend/src/common/common.module.ts`	Aggregates common services, middleware, and providers.
`backend/src/common/middleware/csrf.middleware.ts`	Double-submit CSRF check; mints/reads cookie, compares header.
`backend/src/common/guards/jwt-auth.guard.ts`	Global JWT guard; honors `@Public()`.
`backend/src/common/guards/admin.guard.ts`	Requires `req.user.role === 'admin'`.
`backend/src/common/guards/roles.guard.ts`	Enforces `@Roles(...)` metadata.
`backend/src/common/decorators/public.decorator.ts`	`@Public()` marker.
`backend/src/common/decorators/roles.decorator.ts`	`@Roles(...)` metadata.
`backend/src/common/decorators/skip-csrf.decorator.ts`	`@SkipCsrf()` marker.
`backend/src/common/filters/global-exception.filter.ts`	Converts all errors to the standard envelope.
`backend/src/common/pipes/zod-validation.pipe.ts`	Validates body/param/query with a zod schema.
`backend/src/common/interceptors/transform.interceptor.ts`	Optional response transformer.
`backend/src/common/services/event-status.service.ts`	Computes event `Stopped`/`Running` and `countdownMs`.
`backend/src/common/services/login-backoff.service.ts`	Per-IP+username failed-login throttle.
`backend/src/common/services/registration-rate-limit.service.ts`	Per-IP first-admin registration throttle.
`backend/src/common/services/sse-hub.service.ts`	In-process pub/sub for event status and scoreboard streams.
`backend/src/common/utils/openapi31.ts`	Converts the Nest-generated OpenAPI 3.0 doc to OpenAPI 3.1.
`backend/src/common/utils/password-policy.ts`	Argon2 password validator (length, mixed-case policy).
`backend/src/common/utils/theme-loader.service.ts`	Loads themes from disk, backfills built-ins, validates tokens.
`backend/src/common/utils/upload.ts`	Upload size-limit parser + filename sanitizer.
`backend/src/common/types/theme.ts`, `theme-ids.ts`	`Theme` interface and the 10 canonical `ThemeId`s.
`backend/src/common/errors/api-error.ts`	`ApiError` class (status + machine code + message + details).
`backend/src/common/errors/error-codes.ts`	Canonical `ERROR_CODES` enum.

Modules

File	Responsibility
`backend/src/modules/auth/auth.module.ts`	Wires `AuthController`, `AuthService`, `JwtStrategy`.
`backend/src/modules/auth/auth.controller.ts`	`/api/v1/auth/{login,refresh,logout,csrf}`.
`backend/src/modules/auth/auth.service.ts`	Login, refresh, logout, register-first-admin, mint JWT + refresh tokens.
`backend/src/modules/auth/cookie.ts`	`setRefreshCookie` / `clearRefreshCookie` helpers.
`backend/src/modules/auth/dto/auth.dto.ts`	Zod schemas for login + refresh.
`backend/src/modules/auth/strategies/jwt.strategy.ts`	Passport JWT strategy.
`backend/src/modules/users/users.module.ts`	Wires `UsersController` + `UsersService`.
`backend/src/modules/users/users.controller.ts`	`/api/v1/auth/register-first-admin`.
`backend/src/modules/users/users.service.ts`	`enforceLastAdminInvariant` helper.
`backend/src/modules/users/dto/create-first-admin.dto.ts`	Zod schema for first-admin registration.
`backend/src/modules/setup/setup.module.ts`	Wires `SetupController` + `SetupService` (dedicated first-admin bootstrap flow).
`backend/src/modules/setup/setup.controller.ts`	`POST /api/v1/setup/create-admin` (returns 404 once an admin exists).
`backend/src/modules/setup/setup.service.ts`	Hashes password (Argon2id), runs the create inside a transaction, mints session via `AuthService.createSession`.
`backend/src/modules/setup/dto/create-admin.dto.ts`	Zod schema with `password === passwordConfirm` refine.
`backend/src/modules/admin/admin.module.ts`	Wires `AdminController` + `AdminService`.
`backend/src/modules/admin/admin.controller.ts`	`/api/v1/admin/users[/{id}]`.
`backend/src/modules/admin/admin.service.ts`	list / create / update role / delete user with last-admin guard.
`backend/src/modules/admin/dto/admin.dto.ts`	Zod schemas for admin endpoints.
`backend/src/modules/system/system.module.ts`	Wires `SystemController` + `SystemService` + status + hub services.
`backend/src/modules/system/system.controller.ts`	`/api/v1/{bootstrap,event/status}` + SSE `/event/stream`, `/scoreboard/stream`.
`backend/src/modules/system/system.service.ts`	Builds the public bootstrap payload from settings + theme + admin count.
`backend/src/modules/uploads/uploads.module.ts`	Wires `UploadsController`.
`backend/src/modules/uploads/uploads.controller.ts`	`/api/v1/uploads/{category-icon,challenge-file}`.
`backend/src/modules/settings/settings.module.ts`	`SettingsService` (get/set/getAll over the `setting` table).
`backend/src/frontend/frontend.module.ts`	Wires SPA fallback + uploads static middleware.
`backend/src/frontend/spa.controller.ts`	`SpaFallbackMiddleware` (returns `index.html` for client routes).
`backend/src/frontend/uploads-static.middleware.ts`	Mounts `/uploads` static helper.

Themes

File	Responsibility
`backend/themes/01-classic.json`	`classic` theme tokens.
`backend/themes/02-midnight.json` … `10-monochrome.json`	The other 9 canonical themes.

Frontend

File	Responsibility
`frontend/src/main.ts`	Bootstraps the standalone Angular app + registers interceptors.
`frontend/src/index.html`	Root HTML shell.
`frontend/src/styles.css`	Global styles consuming theme CSS custom properties.
`frontend/src/app/app.component.ts`	Root component; triggers bootstrap on init.
`frontend/src/app/app.routes.ts`	Angular route table.
`frontend/src/app/core/services/auth.service.ts`	Signal store for access token + current user.
`frontend/src/app/core/services/bootstrap.service.ts`	Fetches `/api/v1/bootstrap` and applies theme tokens to CSS.
`frontend/src/app/core/guards/auth.guard.ts`	`CanActivateFn` checking init + auth.
`frontend/src/app/core/interceptors/auth.interceptor.ts`	Attaches Bearer header.
`frontend/src/app/core/interceptors/csrf.interceptor.ts`	Attaches `X-CSRF-Token` on unsafe methods.
`frontend/src/app/features/auth/login.component.ts`	Login form.
`frontend/src/app/features/setup/setup-create-admin.component.ts`	First-admin modal overlay (non-dismissible; typed reactive form).
`frontend/src/app/features/setup/setup-create-admin.service.ts`	POSTs to `/api/v1/setup/create-admin` and tags the result with the error code.
`frontend/src/app/features/setup/setup-create-admin.validators.ts`	Standalone `passwordMatchValidator` group-level reactive form validator.
`frontend/src/app/features/home/home.component.ts`	Landing page after auth.

Tests

File	Responsibility
`tests/backend/*.spec.ts` (18 suites)	Jest tests for backend modules, CSRF, OpenAPI 3.1, migrations, rate limits.
`tests/frontend/theme.spec.ts`	Jest test for theme token application.
`tests/backend/csrf-client.ts`	Test helper for CSRF flow.
`tests/backend/db-helper.ts`	Test helper for spinning up an isolated DB.

15 KiB Raw Blame History

Backend

Entrypoint & config

Database

Common

Modules

Themes

Frontend

Tests

See also

15 KiB

Raw Blame History