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-21T18:45:54Z.

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, and guards.
• 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, 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, and SSE streams.
• 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.
• 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 event window and live countdown work.
• Scoreboard Stream - How live solves are broadcast to clients.