59 lines
5.6 KiB
Markdown
59 lines
5.6 KiB
Markdown
---
|
|
type: architecture
|
|
title: Key Files Index
|
|
description: One-line responsibility for important source files, including bootstrap payloads, runtime theme application, authenticated event streaming, and validated site-logo uploads.
|
|
tags: [architecture, index, key-files]
|
|
timestamp: 2026-07-22T13:40:00Z
|
|
---
|
|
|
|
# Backend
|
|
|
|
| File | Responsibility |
|
|
|---|---|
|
|
| `backend/src/main.ts` | Bootstraps Nest, middleware, OpenAPI, static assets, and SPA fallback. |
|
|
| `backend/src/app.module.ts` | Wires feature modules and global providers. |
|
|
| `backend/src/database/database.module.ts` | Configures TypeORM with SQLite. |
|
|
| `backend/src/database/database-init.service.ts` | Initializes the database and runs migrations. |
|
|
| `backend/src/common/guards/jwt-auth.guard.ts` | Global JWT authorization guard. |
|
|
| `backend/src/common/middleware/csrf.middleware.ts` | Double-submit CSRF protection. |
|
|
| `backend/src/common/services/event-status.service.ts` | Computes the event-window state machine. |
|
|
| `backend/src/common/services/sse-hub.service.ts` | In-process pub/sub for server-sent event streams. |
|
|
| `backend/src/modules/system/system.controller.ts` | Registers bootstrap, event status, settings, and SSE endpoints. |
|
|
| `backend/src/modules/system/system.service.ts` | Builds the public bootstrap payload from admin existence, settings, the theme loader, and password-policy configuration. |
|
|
| `backend/src/modules/admin/admin-general.controller.ts` | Registers admin general-settings and available-theme endpoints. |
|
|
| `backend/src/modules/admin/general.service.ts` | Reads/writes global settings, filters available theme files, and publishes the `general` SSE notification after updates. |
|
|
| `backend/src/modules/auth/auth.controller.ts` | Registers authentication and account endpoints. |
|
|
| `backend/src/modules/auth/auth.service.ts` | Handles sessions, authentication, registration, and password changes. |
|
|
| `backend/src/modules/uploads/uploads.controller.ts` | Registers admin-only multipart uploads, including Sharp-backed site-logo format validation. |
|
|
| `backend/src/modules/admin/dto/general.dto.ts` | Zod schema for `PUT /api/v1/admin/general/settings` — string-length rules, theme-key enum, ISO-8601 datetime check on the event-window fields (empty string allowed), and the `endAfterStart` super-refine. |
|
|
|
|
# Frontend
|
|
|
|
| File | Responsibility |
|
|
|---|---|
|
|
| `frontend/src/main.ts` | Bootstraps Angular and registers HTTP interceptors. |
|
|
| `frontend/src/app/app.routes.ts` | Defines public, shell, child, and admin routes. |
|
|
| `frontend/src/app/core/services/bootstrap.service.ts` | Caches and exposes bootstrap state, refreshes it after admin updates, and applies the resolved theme. |
|
|
| `frontend/src/app/core/services/bootstrap.types.ts` | Defines bootstrap/theme payload types and maps theme tokens to CSS custom properties. |
|
|
| `frontend/src/app/core/services/admin.service.ts` | Calls admin settings, theme-list, category, and upload APIs. |
|
|
| `frontend/src/app/features/home/home.component.ts` | Authenticated shell container; starts user and event state services. |
|
|
| `frontend/src/app/core/services/auth.service.ts` | Signal-backed access token and current-user state; owns the cross-tab invalidation `BroadcastChannel` + `storage`-event fallback. |
|
|
| `frontend/src/app/core/services/auth-session-events.pure.ts` | Pure cross-tab message encoding/validation and namespaced constants used by the auth broadcast channel. |
|
|
| `frontend/src/app/core/services/authenticated-event-source.service.ts` | Fetch-based authenticated SSE transport with frame parsing, abort support, and a separate `'unauthorized'` event for `401`/`403`. |
|
|
| `frontend/src/app/core/services/event-status.store.ts` | Event state signal store, one-second countdown timer, and the optional `onUnauthorized` callback wiring. |
|
|
| `frontend/src/app/core/services/event-status.pure.ts` | Event payload types, transport interface (including `'unauthorized'` listener), pure countdown helpers, and the `LED_COLOR_BY_STATE` map used by the shell LED. |
|
|
| `frontend/src/app/features/home/home.component.ts` | Authenticated shell container; starts user and event state services, subscribes to peer invalidation, and navigates to `/login` when the session is invalidated elsewhere. |
|
|
| `frontend/src/app/features/shell/header/shell-header.component.ts` | Shell title, status LED (size/shape only — color comes from the pure map via `[style.background-color]`), countdown, and user menu. |
|
|
| `frontend/src/app/features/shell/tabs/quick-tabs.component.ts` | Main shell navigation tabs. |
|
|
| `frontend/src/app/features/shell/change-password/change-password-modal.component.ts` | Change-password form modal. |
|
|
| `frontend/src/app/features/admin/general.component.ts` | `AdminGeneralComponent` reactive form for `/admin/general` — per-field inline error rendering (page-title + event-start + event-end), logo upload wiring, welcome Markdown preview, event-state derivation, and SSE `general` event handling. |
|
|
| `frontend/src/app/features/admin/general.pure.ts` | Pure helpers used by `AdminGeneralComponent` — `deriveEventState`, `endAfterStartValidator`, `normalizePageTitle`, `toIsoUtc`, `toDatetimeLocal`, `pageTitleError` / `pageTitleMessage`, `isoDatetimeValidator`, and `datetimeMessage`. |
|
|
| `tests/frontend/authenticated-event-source.spec.ts` | Tests SSE authorization, frame transport behavior, and the `401`/`403` unauthorized path. |
|
|
| `tests/frontend/auth-session-events.spec.ts` | Pure tests for cross-tab invalidation message encoding, payload validation, and `storage`-event filtering. |
|
|
|
|
# See also
|
|
|
|
- [Frontend Structure](/architecture/frontend-structure.md)
|
|
- [Authenticated Shell](/guides/authenticated-shell.md)
|
|
- [System Endpoints](/api/system.md)
|