HIPCTF2/docs/index.md

okf_version

okf_version
0.1

HIPCTF Documentation

HIPCTF is a single-tenant CTF (Capture-The-Flag) platform built as a Node.js monorepo containing a NestJS REST API and an Angular single-page application. It supports user registration, authentication, challenge management, a live scoreboard, an event window with a public countdown, theming, and admin controls.

The docs below are organized by purpose so agents can pull just the slice they need. Last regenerated 2026-07-22T09:03:53Z.

Architecture

• System Overview - High-level layout of the backend, frontend, and how they communicate.
• Backend Module Map - NestJS modules, controllers, services, and their wiring.
• Frontend Structure - Angular routes, components, services, guards, and stores (including the authenticated shell
  • signal stores).
• Key Files Index - One-line summary of every important source file in the repository.

Database

• Schema Overview - Tables, relationships, and indexes.
• User Table - user table schema and seed behavior.
• Challenge Tables - category, challenge, challenge_file, solve tables.
• Auth and Settings Tables - refresh_token and setting tables.
• Blog Post Table - blog_post table.

API

• REST API Overview - Base URL, versioning, auth, CSRF, and error envelope.
• Auth Endpoints - Login, refresh, logout, CSRF, /me, /change-password, and first-admin registration.
• Setup Endpoint - Dedicated POST /api/v1/setup/create-admin used only while no administrator exists.
• Admin Endpoints - User management endpoints (admin role required).
• System Endpoints - Bootstrap, event status, public SSE streams, public event-window settings, and the authenticated /events/status SSE stream.
• Uploads Endpoints - Admin-only multipart uploads.

Guides

• First-Run Bootstrap - How a fresh instance is initialized by the very first admin via the non-dismissible modal.
• Setup Form Field Errors - Pure helpers that translate reactive-form state into the inline validation messages on the first-admin modal.
• Admin Shell & User Management - How admins navigate the post-login shell and reach the user-management area.
• Authenticated Shell - The header, LED
  • countdown, quick-jump tabs, user menu, and SSE lifecycle that frame every signed-in page.
• Change Password - How a signed-in user changes their own password, including every error branch and the refresh-token revocation behavior.
• Session Restoration on Reload - How the SPA keeps a user signed in across hard refreshes and how the guards wait for bootstrap + auth hydration before deciding where to route.
• Landing Page - Public landing page (logo, welcome Markdown, blog list) and the login + registration modal rendered at /login once the instance is initialized.
• Theming - How themes are loaded and applied.
• Event Window - How the 4-state event window and live countdown work, including the authenticated SSE stream.
• Scoreboard Stream - How live solves are broadcast to clients.