HIPCTF2/docs/architecture/frontend-structure.md

type, title, description, tags, timestamp

type	title	description	tags	timestamp
architecture	Frontend Structure	Angular routes, components, services, guards, interceptors, and authenticated SSE transport.	architecture frontend angular shell sse	2026-07-22T09:22:34Z

Routes

Routes live in frontend/src/app/app.routes.ts:

Path	Component	Guard	Notes
/bootstrap	SetupCreateAdminComponent	—	First-admin creation flow.
/login	LandingComponent	landingGuard	Public landing and authentication modal.
/	HomeComponent	authGuard	Authenticated shell and child outlet.
/challenges	ChallengesPage	inherited	Placeholder challenges page.
/scoreboard	ScoreboardPage	inherited	Placeholder scoreboard page.
/blog	BlogPage	inherited	Placeholder blog page.
/admin	AdminUsersComponent	adminGuard	Admin-only child route.

Components and services

Symbol	Path	Responsibility
HomeComponent	frontend/src/app/features/home/home.component.ts	Smart shell; owns navigation signals, user hydration, change-password flow, and event-stream lifecycle.
ShellHeaderComponent	frontend/src/app/features/shell/header/shell-header.component.ts	Renders title, active section, event LED/countdown, and user menu; contains component-scoped LED styling.
QuickTabsComponent	frontend/src/app/features/shell/tabs/quick-tabs.component.ts	Emits navigation events for Challenges, Scoreboard, and Blog.
EventStatusStore	frontend/src/app/core/services/event-status.store.ts	Applies event state frames and computes countdown text.
AuthenticatedEventSourceService	frontend/src/app/core/services/authenticated-event-source.service.ts	Opens authenticated SSE over fetch, parsing streamed frames into EventSourceLike events.
AuthService	frontend/src/app/core/services/auth.service.ts	Stores the access token used by the authenticated SSE transport.
UserStore	frontend/src/app/core/services/user.store.ts	Hydrates the signed-in user and rank data.

Authenticated SSE wiring

HomeComponent.ngOnInit() calls EventStatusStore.start() with a factory for AuthenticatedEventSourceService.open('/api/v1/events/status'). The transport:

1. Reads the access token from AuthService.
2. Sends Accept: text/event-stream, optional Authorization: Bearer <token>, credentials: 'include', and an AbortSignal.
3. Reads the response body with a stream reader and decodes UTF-8 chunks.
4. Splits complete SSE records on blank lines, joins repeated data: lines, and dispatches MessageEvent objects.
5. Buffers records received before the message listener is attached.
6. Aborts and clears listeners when close() is called.

EventStatusStore parses each message as EventStatePayload, updates its signals, and runs a one-second local timer. HomeComponent stops the store on destruction.

Key integration files

File	Responsibility
frontend/src/app/app.routes.ts	Registers shell and child routes.
frontend/src/app/core/interceptors/auth.interceptor.ts	Adds Bearer authentication to Angular HTTP requests.
frontend/src/app/core/services/authenticated-event-source.service.ts	Adds Bearer authentication to the browser SSE request, which does not use the Angular HTTP interceptor chain.
frontend/src/app/core/services/event-status.pure.ts	Defines the event payload and transport interface.
tests/frontend/authenticated-event-source.spec.ts	Regression coverage for authenticated SSE transport behavior.

See also

• Authenticated Shell
• Event Window
• System Overview