# saber20005/blackbox-lab architecture

> Architecture diagram of the GitHub repository saber20005/blackbox-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saber20005/blackbox-lab
- Repository: https://github.com/saber20005/blackbox-lab

## Overview

BLACKBOX Lab is an Arabic static cybersecurity training application. Learners choose a track and stage, work through guided exercises, and save progress, notes, and results; the app also provides account sync, linked skills, planning, and learner reporting. The graph includes the documented training and learner-tool branches, while showing only relationships supported by the excerpts, SOURCE INDEX, or README. Some peripheral page implementations were not sampled, so their internal connections are omitted.

Main entry points: [`app.js`](https://github.com/saber20005/blackbox-lab/blob/main/app.js) (App interface), [`functions/index.js`](https://github.com/saber20005/blackbox-lab/blob/main/functions/index.js) (Grading endpoints), [`account-sync.js`](https://github.com/saber20005/blackbox-lab/blob/main/account-sync.js) (Account sync), [`firebase-client.js`](https://github.com/saber20005/blackbox-lab/blob/main/firebase-client.js) (Firebase adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Training experience"]
  node_app["App interface<br/>[app.js]"]
  node_routing["Route handling<br/>[routes.js]"]
  node_curriculum["Track content<br/>[data.js]"]
  node_defense["Defense tracks<br/>[defense-tracks.js]"]
  node_evidence["Evidence workbench"]
end

subgraph group_state["Progress and accounts"]
  node_progress["Progress and backups<br/>[progress.js]"]
  node_account_ui["Account interface<br/>[account-ui.js]"]
  node_sync["Account sync<br/>[account-sync.js]"]
  node_firebase["Firebase adapter<br/>[firebase-client.js]"]
end

subgraph group_learner_tools["Learner tools"]
  node_skills["Linked skills"]
  node_catalog["CyberTrace catalog"]
  node_session_plan["Session planning<br/>[training-plan.js]"]
  node_plan_ui["Planning interface"]
  node_mission["Missions<br/>[mission-mode.js]"]
  node_portfolio["Portfolio<br/>[portfolio.js]"]
  node_portfolio_page["Portfolio page<br/>[portfolio-page.js]"]
  node_vm_inspector["Local VM inspector<br/>[vm_inspector.py]"]
  node_analytics["Usage analytics<br/>[analytics.js]"]
end

subgraph group_verified["Verified assessments"]
  node_grading_client["Grading client"]
  node_grading_api["Grading endpoints<br/>[index.js]"]
  node_grading_sessions["Session allocation<br/>[session-store.js]"]
  node_grading_rules["Answer grading<br/>[grading-core.js]"]
  node_soc_service["SOC assessment service"]
  node_soc_rules["SOC scoring rules"]
end

node_learner(("Learner"))
node_cloud[("Firebase services")]

node_learner -->|"uses"| node_app
node_app -->|"parses routes"| node_routing
node_routing -->|"validates tracks"| node_curriculum
node_app -->|"renders training"| node_curriculum
node_curriculum -->|"includes tracks"| node_defense
node_app -->|"loads and saves"| node_progress
node_app -->|"uses workbench"| node_evidence
node_app -->|"uses account UI"| node_account_ui
node_app -->|"saves account data"| node_sync
node_sync -->|"normalizes state"| node_progress
node_sync -->|"creates backend"| node_firebase
node_firebase -->|"reads and writes"| node_cloud
node_firebase -->|"normalizes receipts"| node_catalog
node_app -->|"renders skills"| node_skills
node_skills -->|"aggregates receipts"| node_catalog
node_app -->|"uses planner UI"| node_plan_ui
node_plan_ui -->|"builds session plan"| node_session_plan
node_app -.->|"provides missions"| node_mission
node_app -.->|"provides portfolio"| node_portfolio_page
node_portfolio_page -->|"uses portfolio data"| node_portfolio
node_learner -->|"runs locally"| node_vm_inspector
node_app -->|"submits answers"| node_grading_client
node_grading_client -.->|"calls assessment service"| node_grading_api
node_grading_api -->|"allocates sessions"| node_grading_sessions
node_grading_api -->|"validates cases"| node_grading_rules
node_grading_api -->|"dispatches SOC checks"| node_soc_service
node_soc_service -->|"validates and scores"| node_soc_rules
node_app -->|"records events"| node_analytics

click node_app "https://github.com/saber20005/blackbox-lab/blob/main/app.js"
click node_routing "https://github.com/saber20005/blackbox-lab/blob/main/routes.js"
click node_curriculum "https://github.com/saber20005/blackbox-lab/blob/main/data.js"
click node_defense "https://github.com/saber20005/blackbox-lab/blob/main/defense-tracks.js"
click node_evidence "https://github.com/saber20005/blackbox-lab/blob/main/evidence-workbench.js"
click node_progress "https://github.com/saber20005/blackbox-lab/blob/main/progress.js"
click node_account_ui "https://github.com/saber20005/blackbox-lab/blob/main/account-ui.js"
click node_sync "https://github.com/saber20005/blackbox-lab/blob/main/account-sync.js"
click node_firebase "https://github.com/saber20005/blackbox-lab/blob/main/firebase-client.js"
click node_skills "https://github.com/saber20005/blackbox-lab/blob/main/linked-skills-ui.js"
click node_catalog "https://github.com/saber20005/blackbox-lab/blob/main/cybertrace-catalog.js"
click node_session_plan "https://github.com/saber20005/blackbox-lab/blob/main/training-plan.js"
click node_plan_ui "https://github.com/saber20005/blackbox-lab/blob/main/training-plan-ui.js"
click node_mission "https://github.com/saber20005/blackbox-lab/blob/main/mission-mode.js"
click node_portfolio "https://github.com/saber20005/blackbox-lab/blob/main/portfolio.js"
click node_portfolio_page "https://github.com/saber20005/blackbox-lab/blob/main/portfolio-page.js"
click node_vm_inspector "https://github.com/saber20005/blackbox-lab/blob/main/local-agent/vm_inspector.py"
click node_grading_client "https://github.com/saber20005/blackbox-lab/blob/main/verified-grading-client.js"
click node_grading_api "https://github.com/saber20005/blackbox-lab/blob/main/functions/index.js"
click node_grading_sessions "https://github.com/saber20005/blackbox-lab/blob/main/functions/session-store.js"
click node_grading_rules "https://github.com/saber20005/blackbox-lab/blob/main/functions/grading-core.js"
click node_soc_service "https://github.com/saber20005/blackbox-lab/blob/main/functions/soc-verified-service.js"
click node_soc_rules "https://github.com/saber20005/blackbox-lab/blob/main/functions/soc-verified-core.js"
click node_analytics "https://github.com/saber20005/blackbox-lab/blob/main/analytics.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_routing,node_curriculum,node_defense,node_evidence toneBlue
class node_progress,node_account_ui,node_sync,node_firebase,node_cloud toneAmber
class node_skills,node_catalog,node_session_plan,node_plan_ui,node_mission,node_portfolio,node_portfolio_page,node_vm_inspector,node_analytics toneMint
class node_grading_client,node_grading_api,node_grading_sessions,node_grading_rules,node_soc_service,node_soc_rules toneRose
class node_learner toneIndigo
```

## Components

### Training experience

- [App interface](https://github.com/saber20005/blackbox-lab/blob/main/app.js): `app.js`
- [Route handling](https://github.com/saber20005/blackbox-lab/blob/main/routes.js): `routes.js`
- [Track content](https://github.com/saber20005/blackbox-lab/blob/main/data.js): `data.js`
- [Defense tracks](https://github.com/saber20005/blackbox-lab/blob/main/defense-tracks.js): `defense-tracks.js`
- [Evidence workbench](https://github.com/saber20005/blackbox-lab/blob/main/evidence-workbench.js): `evidence-workbench.js`

### Progress and accounts

- [Progress and backups](https://github.com/saber20005/blackbox-lab/blob/main/progress.js): `progress.js`
- [Account interface](https://github.com/saber20005/blackbox-lab/blob/main/account-ui.js): `account-ui.js`
- [Account sync](https://github.com/saber20005/blackbox-lab/blob/main/account-sync.js): `account-sync.js`
- [Firebase adapter](https://github.com/saber20005/blackbox-lab/blob/main/firebase-client.js): `firebase-client.js`

### Learner tools

- [Linked skills](https://github.com/saber20005/blackbox-lab/blob/main/linked-skills-ui.js): `linked-skills-ui.js`
- [CyberTrace catalog](https://github.com/saber20005/blackbox-lab/blob/main/cybertrace-catalog.js): `cybertrace-catalog.js`
- [Session planning](https://github.com/saber20005/blackbox-lab/blob/main/training-plan.js): `training-plan.js`
- [Planning interface](https://github.com/saber20005/blackbox-lab/blob/main/training-plan-ui.js): `training-plan-ui.js`
- [Missions](https://github.com/saber20005/blackbox-lab/blob/main/mission-mode.js): `mission-mode.js`
- [Portfolio](https://github.com/saber20005/blackbox-lab/blob/main/portfolio.js): `portfolio.js`
- [Portfolio page](https://github.com/saber20005/blackbox-lab/blob/main/portfolio-page.js): `portfolio-page.js`
- [Local VM inspector](https://github.com/saber20005/blackbox-lab/blob/main/local-agent/vm_inspector.py): `local-agent/vm_inspector.py`
- [Usage analytics](https://github.com/saber20005/blackbox-lab/blob/main/analytics.js): `analytics.js`

### Verified assessments

- [Grading client](https://github.com/saber20005/blackbox-lab/blob/main/verified-grading-client.js): `verified-grading-client.js`
- [Grading endpoints](https://github.com/saber20005/blackbox-lab/blob/main/functions/index.js): `functions/index.js`
- [Session allocation](https://github.com/saber20005/blackbox-lab/blob/main/functions/session-store.js): `functions/session-store.js`
- [Answer grading](https://github.com/saber20005/blackbox-lab/blob/main/functions/grading-core.js): `functions/grading-core.js`
- [SOC assessment service](https://github.com/saber20005/blackbox-lab/blob/main/functions/soc-verified-service.js): `functions/soc-verified-service.js`
- [SOC scoring rules](https://github.com/saber20005/blackbox-lab/blob/main/functions/soc-verified-core.js): `functions/soc-verified-core.js`

### Other components

- **Learner**
- **Firebase services**

## Connections

- Learner → App interface: uses (evidence: `README.md`)
- App interface → Route handling: parses routes (evidence: `app.js`)
- Route handling → Track content: validates tracks (evidence: `routes.js`)
- App interface → Track content: renders training (evidence: `app.js`)
- Track content → Defense tracks: includes tracks (evidence: `data.js`)
- App interface → Progress and backups: loads and saves (evidence: `app.js`)
- App interface → Evidence workbench: uses workbench (evidence: `app.js`)
- App interface → Account interface: uses account UI (evidence: `app.js`)
- App interface → Account sync: saves account data (evidence: `app.js`)
- Account sync → Progress and backups: normalizes state (evidence: `account-sync.js`)
- Account sync → Firebase adapter: creates backend (evidence: `account-sync.js`)
- Firebase adapter → Firebase services: reads and writes (evidence: `firebase-client.js`)
- Firebase adapter → CyberTrace catalog: normalizes receipts (evidence: `firebase-client.js`)
- App interface → Linked skills: renders skills (evidence: `app.js`)
- Linked skills → CyberTrace catalog: aggregates receipts (evidence: `linked-skills-ui.js`)
- App interface → Planning interface: uses planner UI (evidence: `app.js`)
- Planning interface → Session planning: builds session plan (evidence: `training-plan-ui.js`)
- App interface → Missions: provides missions
- App interface → Portfolio page: provides portfolio
- Portfolio page → Portfolio: uses portfolio data (evidence: `portfolio-page.js`)
- Learner → Local VM inspector: runs locally (evidence: `README.md`)
- App interface → Grading client: submits answers (evidence: `app.js`)
- Grading client → Grading endpoints: calls assessment service
- Grading endpoints → Session allocation: allocates sessions (evidence: `functions/index.js`)
- Grading endpoints → Answer grading: validates cases (evidence: `functions/index.js`)
- Grading endpoints → SOC assessment service: dispatches SOC checks (evidence: `functions/index.js`)
- SOC assessment service → SOC scoring rules: validates and scores (evidence: `functions/soc-verified-service.js`)
- App interface → Usage analytics: records events (evidence: `app.js`)
