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-22T21:25:29Z.

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.
• Category Repair Migration - Forward-only migration that adds created_at/updated_at to legacy category tables and reconciles system rows to the canonical CRY/HW/MSC/PWN/REV/WEB set.
• 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 - Admin-only endpoints covering user management, general settings (/api/v1/admin/general/*), and categories (/api/v1/admin/categories/*).
• 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 for category icons, challenge files, and validated site logos.

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 & Side Navigation - How admins navigate the post-login admin area side-nav (General, Challenges, Players, Blog, System) and reach the enabled child pages.
• Admin — General Settings - How an admin edits platform-wide settings, including the required and strictly ordered event window, at /admin/general.
• Admin — Categories - How an admin lists, creates, edits, and deletes challenge categories at /admin/categories, including system-row and challenge-attached protection.
• Admin — Challenges - How an admin lists, searches, creates, edits, deletes, imports, and exports challenges at /admin/challenges, including file staging and overwrite confirm.
• 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.
• Cross-Tab Authenticated Shell Invalidation - How a logout in one tab, or an unauthorized SSE response, instantly clears and redirects every other open tab of the SPA.
• Local Development Workflow - How to run the backend and frontend together (npm run dev), the Angular dev-server proxy, and the project-local ./data/ directory.
• 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 canonical themes are listed for admins, persisted through general settings, and applied to CSS custom properties.
• Event Window - How the 4-state event window and live countdown work, including the authenticated SSE stream.
• Event LED Color Mapping - Source of truth for the shell status dot's color in each EventState.
• Scoreboard Stream - How live solves are broadcast to clients.