# tni-cybersec/tnicybersec-cwc architecture

> Architecture diagram of the GitHub repository tni-cybersec/tnicybersec-cwc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tni-cybersec/tnicybersec-cwc
- Repository: https://github.com/tni-cybersec/tnicybersec-cwc

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices-style platform for running CTF (Jeopardy) and King-of-the-Hill competitions.
- Key capabilities: real-time score tracking, KOTH capture events, custom scoring hooks, web UI for players/admins, Java-based simulators for testing, and SDKs for extension.

##### File Structure
- Top-level service/component folders:
- ctf-web-frontend (Vue.js SPA)
- ctf-web-backend (Firebase Cloud Functions + Firestore)
- ctf-koth-endpoint-agent (Node.js)
- ctf-koth-tracking-server (Node.js)
- custom-scoring-sdk (TypeScript library)
- capturesim / capturesim-cwc2020 (Java simulation frameworks)
- point-calculator (Java point calculation service)
- web-dashboard-sample (static HTML/JS demo)
- guides + write-ups (documentation, not part of runtime)

##### README
- Confirms the repo is “CWC” – a CTF & KOTH cybersecurity competition platform.

a. Main Components
- Frontend: Vue.js SPA (ctf-web-frontend)
- Backend: Firebase Firestore + Cloud Functions (ctf-web-backend)
- KOTH Capture Pipeline:
– Endpoint Agent (Node.js)
– Tracking Server (Node.js)
- Scoring & Rules:
– custom-scoring-sdk (TS library)
– point-calculator service (Java)
- Simulation/Test Harness: capturesim, capturesim-cwc2020 (Java)
- Static Dashboard Demo: web-dashboard-sample

b. Relationships & Data Flows
1. User (Admin/Player) ↔ Vue SPA
2. Vue SPA ⇄ Firestore (reads/writes game state, scores, profiles)
3. Firestore triggers Cloud Functions for:
– onFlagAnswered, onItemPurchased, onMissionChanged, etc.
4. Endpoint Agent monitors real KOTH servers, generates push IDs, posts events to the Tracking Server.
5. Tracking Server writes KOTH capture events into Firestore (via Firebase SDK).
6. Point-Calculator service (if run as standalone or triggered via Cloud Functions) applies custom point logic (via custom-scoring-sdk).
7. Simulators connect to GameService APIs or directly invoke FlagService/HillService to model games for offline testing.

c. Architectural Patterns & Principles
- Frontend/Backend separation with serverless backend (Firebase).
- Event-driven architecture using Firestore triggers.
- Modular scoring via an SDK so custom rules can be pluggable.
- Microservice agents for real-time KOTH capture ingestion.
- Java-based simulators follow Strategy pattern for games/scenarios.

d. Key Technologies
- ctf-web-frontend: Vue.js, Vuex, Vue Router, Firebase JS SDK
- ctf-web-backend: Node.js, Firebase Cloud Functions, Firestore, Firebase Security Rules
- Endpoint & Tracker: Node.js, Firebase Admin SDK
- custom-scoring-sdk: TypeScript, npm, Firebase SDK, Event Emitter
- Point Calculator & Simulators: Java, Maven, custom Java interfaces/services

##### Don’t Overthink—Be Exhaustive
- Firestore triggers from functions/src/triggers.
- Custom-scoring-sdk as a shared library referenced by both Cloud Functions and point-calculator.
- Interactions, even if flows are simple read/write operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        direction TB
        User["Admin/Player"]:::external
        SPA["Vue.js SPA"]:::frontend
    end

    subgraph "Firebase Project"
        direction TB
        Firestore["Firestore"]:::backend
        CloudFuncs["Cloud Functions"]:::backend
        Rules["Firestore Rules & Indexes"]:::backend
    end

    subgraph "KOTH Pipeline"
        direction TB
        Agent["KOTH Endpoint Agent"]:::microservice
        Tracker["KOTH Tracking Server"]:::microservice
    end

    subgraph "Scoring Services"
        direction TB
        SDK["custom-scoring-sdk"]:::library
        PointCalc["Point Calculator Service"]:::java
    end

    subgraph "Simulation Suite"
        direction TB
        SimCWC["CWC2020 Simulator"]:::java
        SimCore["CaptureSim Core Framework"]:::java
    end

    subgraph "Demo"
        direction TB
        Demo["Static Dashboard Demo"]:::demo
    end

    User -->|"interacts with"| SPA
    SPA -->|"Firestore write/read"| Firestore
    Firestore -->|"triggers"| CloudFuncs
    CloudFuncs -->|"uses SDK"| SDK
    CloudFuncs -->|"Firestore operations"| Firestore
    Agent -->|"push event"| Tracker
    Tracker -->|"Firestore write"| Firestore
    PointCalc -->|"uses SDK"| SDK
    SimCWC -->|"invokes APIs"| CloudFuncs
    SimCWC -->|"extends"| SimCore
    Demo -->|"reads from"| Firestore

    click SPA "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/ctf-web-frontend/"
    click CloudFuncs "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/ctf-web-backend/functions/"
    click Rules "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-web-backend/firestore.rules"
    click Rules "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-web-backend/firestore.indexes.json"
    click Rules "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-web-backend/database.rules.json"
    click Rules "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-web-backend/storage.rules"
    click Agent "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-koth-endpoint-agent/index.js"
    click Agent "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-koth-endpoint-agent/GeneratePushId.js"
    click Tracker "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-koth-tracking-server/index.js"
    click Tracker "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-koth-tracking-server/EndpointTracker.js"
    click Tracker "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/ctf-koth-tracking-server/firebase.config.js"
    click SDK "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/custom-scoring-sdk/src/index.ts"
    click SDK "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/custom-scoring-sdk/src/interfaces/"
    click SDK "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/custom-scoring-sdk/src/models/"
    click SDK "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/custom-scoring-sdk/src/services/"
    click SDK "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/custom-scoring-sdk/src/utilities/"
    click PointCalc "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/point-calculator/src/main/java/cwc2020/calculators/"
    click PointCalc "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/point-calculator/src/main/java/cwc2020/calculators/Config.java"
    click PointCalc "https://github.com/tni-cybersec/tnicybersec-cwc/tree/main/point-calculator/state/"
    click SimCWC "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/capturesim-cwc2020/src/main/java/cwc2020/core/simulators/CyberWarfareContest2020Simulator.java"
    click SimCore "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/capturesim/src/main/java/capturesim/abstracts/DefaultSimulator.java"
    click SimCore "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/capturesim/src/main/java/capturesim/interfaces/Simulator.java"
    click Demo "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/web-dashboard-sample/index.html"
    click Demo "https://github.com/tni-cybersec/tnicybersec-cwc/blob/main/web-dashboard-sample/js/moment.js"

    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef microservice fill:#fff3cd,stroke:#856404,color:#856404;
    classDef java fill:#ffeeba,stroke:#856404,color:#856404;
    classDef library fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef demo fill:#bee5eb,stroke:#0c5460,color:#0c5460;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
```
