---
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-22T13:40:00Z.

# Architecture

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

# Database

* [Schema Overview](/database/schema.md) - Tables, relationships, and indexes.
* [User Table](/database/users.md) - `user` table schema and seed behavior.
* [Challenge Tables](/database/challenges.md) - `category`, `challenge`,
  `challenge_file`, `solve` tables.
* [Auth and Settings Tables](/database/auth-settings.md) - `refresh_token`
  and `setting` tables.
* [Blog Post Table](/database/blog-posts.md) - `blog_post` table.

# API

* [REST API Overview](/api/rest-overview.md) - Base URL, versioning, auth,
  CSRF, and error envelope.
* [Auth Endpoints](/api/auth.md) - Login, refresh, logout, CSRF, `/me`,
  `/change-password`, and first-admin registration.
* [Setup Endpoint](/api/setup.md) - Dedicated `POST /api/v1/setup/create-admin`
  used only while no administrator exists.
* [Admin Endpoints](/api/admin.md) - Admin-only endpoints covering user
  management, general settings (`/api/v1/admin/general/*`), and
  categories (`/api/v1/admin/categories/*`).
* [System Endpoints](/api/system.md) - Bootstrap, event status, public SSE
  streams, public event-window settings, and the authenticated
  `/events/status` SSE stream.
* [Uploads Endpoints](/api/uploads.md) - Admin-only multipart uploads for category icons, challenge files, and validated site logos.

# Guides

* [First-Run Bootstrap](/guides/bootstrap.md) - How a fresh instance is
  initialized by the very first admin via the non-dismissible modal.
* [Setup Form Field Errors](/guides/setup-field-errors.md) - Pure
  helpers that translate reactive-form state into the inline validation
  messages on the first-admin modal.
* [Admin Shell & Side Navigation](/guides/admin-shell.md) - How admins
  navigate the post-login admin area side-nav (General, Challenges,
  Players, Blog, System) and reach the enabled child pages.
* [Admin — General Settings](/guides/admin-general-settings.md) - How an
  admin edits platform-wide settings (page title, logo, theme, event
  window, default challenge IP, registrations, welcome Markdown) at
  `/admin/general`.
* [Admin — Categories](/guides/admin-categories.md) - How an admin lists,
  creates, edits, and deletes challenge categories at `/admin/categories`,
  including system-row and challenge-attached protection.
* [Authenticated Shell](/guides/authenticated-shell.md) - The header, LED
  + countdown, quick-jump tabs, user menu, and SSE lifecycle that frame
  every signed-in page.
* [Change Password](/guides/change-password.md) - How a signed-in user
  changes their own password, including every error branch and the
  refresh-token revocation behavior.
* [Cross-Tab Authenticated Shell Invalidation](/guides/cross-tab-invalidation.md) -
  How a logout in one tab, or an unauthorized SSE response, instantly clears
  and redirects every other open tab of the SPA.
* [Session Restoration on Reload](/guides/session-restoration.md) - 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](/guides/landing-page.md) - Public landing page
  (logo, welcome Markdown, blog list) and the login + registration modal
  rendered at `/login` once the instance is initialized.
* [Theming](/guides/theming.md) - How canonical themes are listed for admins, persisted through general settings, and applied to CSS custom properties.
* [Event Window](/guides/event-window.md) - How the 4-state event
  window and live countdown work, including the authenticated SSE stream.
* [Event LED Color Mapping](/guides/event-led-colors.md) - Source of
  truth for the shell status dot's color in each `EventState`.
* [Scoreboard Stream](/guides/scoreboard-stream.md) - How live solves are
  broadcast to clients.