# saber20005/cybertrace architecture

> Architecture diagram of the GitHub repository saber20005/cybertrace, 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/cybertrace
- Repository: https://github.com/saber20005/cybertrace

## Overview

CyberTrace is an Arabic incident-response training platform. Learners enter through the app, browse or select an investigation, work through incident, evidence, decision, and result stages, then review progress and optionally sync it. Separate branches provide SOC-shift alert triage and server-verified SOC assessment, plus account/BLACKBOX linking and a Pro roadmap. The README documents reports, recommendations, sharing, and optional cloud progress. Some page and integration internals were not sampled; edges below are limited to visible imports/calls or documented capabilities.

Main entry points: [`src/App.jsx`](https://github.com/saber20005/cybertrace/blob/main/src/App.jsx) (App router), [`src/pages/Investigation.jsx`](https://github.com/saber20005/cybertrace/blob/main/src/pages/Investigation.jsx) (Case workflow), [`src/pages/InvestigationLibrary.jsx`](https://github.com/saber20005/cybertrace/blob/main/src/pages/InvestigationLibrary.jsx) (Case library), [`src/pages/SocShift.jsx`](https://github.com/saber20005/cybertrace/blob/main/src/pages/SocShift.jsx) (SOC shift)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application flow"]
  node_app["App router<br/>[App.jsx]"]
  node_pro["Pro roadmap<br/>[Pro.jsx]"]
end

subgraph group_investigations["Incident investigations"]
  node_library["Case library"]
  node_catalog["Case catalog<br/>[caseCatalog.js]"]
  node_case_data["Investigation cases<br/>[cases.js]"]
  node_investigation["Case workflow<br/>[Investigation.jsx]"]
  node_workspace["Evidence workspace"]
  node_workspace_data["Workspace evidence"]
  node_report["Review and report"]
  node_recommendations["Learning recommendations<br/>[learningPlan.js]"]
end

subgraph group_soc["SOC training"]
  node_soc_page["SOC shift<br/>[SocShift.jsx]"]
  node_soc_catalog["Shift and alert catalog<br/>[socShiftCatalog.js]"]
  node_soc_session["Triage session scoring<br/>[socShiftSession.js]"]
  node_verified_soc["Verified SOC assessment<br/>[VerifiedSoc.jsx]"]
  node_verified_backend["Verified SOC service"]
end

subgraph group_progress["Progress and identity"]
  node_progress["Case progress records<br/>[caseProgress.js]"]
  node_xp["XP and levels<br/>[xp.js]"]
  node_cloud["Cloud progress sync<br/>[cloudProgress.js]"]
  node_local_store[("Browser storage")]
  node_firebase[("Firebase auth and data<br/>[firebase.js]")]
  node_auth["Account access<br/>[Auth.jsx]"]
end

subgraph group_blackbox["BLACKBOX integration"]
  node_blackbox_provider["BLACKBOX provider"]
  node_blackbox_controller["Result sync controller<br/>[controller.js]"]
  node_blackbox_backend["BLACKBOX backend<br/>[backend.js]"]
  node_blackbox_link["Learning link and account<br/>[BlackBoxLink.jsx]"]
end

node_learner(("Learner"))
node_blackbox_service[("BLACKBOX service")]

node_learner -->|"opens"| node_app
node_app -->|"routes to"| node_library
node_app -->|"routes to"| node_investigation
node_app -->|"routes to"| node_soc_page
node_app -->|"routes to"| node_verified_soc
node_app -->|"routes to"| node_auth
node_app -->|"routes to"| node_pro
node_library -->|"reads"| node_catalog
node_catalog -->|"loads cases"| node_case_data
node_library -->|"reads progress"| node_progress
node_library -->|"gets guidance"| node_recommendations
node_investigation -->|"gets case details"| node_catalog
node_investigation -->|"renders"| node_workspace
node_workspace -->|"loads evidence"| node_workspace_data
node_investigation -->|"records result"| node_progress
node_investigation -->|"awards XP"| node_xp
node_investigation -->|"creates report"| node_report
node_soc_page -->|"loads shift"| node_soc_catalog
node_soc_page -->|"uses session"| node_soc_session
node_soc_session -->|"grades alerts"| node_soc_catalog
node_soc_session -->|"reads and writes"| node_local_store
node_verified_soc -->|"requests assessment"| node_verified_backend
node_verified_backend -.->|"uses service"| node_blackbox_service
node_progress -->|"reads and writes"| node_local_store
node_xp -->|"persists XP"| node_local_store
node_app -->|"checks sync"| node_cloud
node_cloud -->|"syncs through"| node_firebase
node_auth -->|"authenticates"| node_firebase
node_blackbox_provider -->|"provides controller"| node_blackbox_controller
node_blackbox_controller -->|"creates backend"| node_blackbox_backend
node_blackbox_backend -.->|"connects to"| node_blackbox_service
node_investigation -->|"uses account context"| node_blackbox_provider
node_investigation -->|"offers lab link"| node_blackbox_link
node_auth -->|"shows linking control"| node_blackbox_link

click node_app "https://github.com/saber20005/cybertrace/blob/main/src/App.jsx"
click node_library "https://github.com/saber20005/cybertrace/blob/main/src/pages/InvestigationLibrary.jsx"
click node_catalog "https://github.com/saber20005/cybertrace/blob/main/src/data/caseCatalog.js"
click node_case_data "https://github.com/saber20005/cybertrace/blob/main/src/data/cases.js"
click node_investigation "https://github.com/saber20005/cybertrace/blob/main/src/pages/Investigation.jsx"
click node_workspace "https://github.com/saber20005/cybertrace/blob/main/src/components/InvestigationWorkspace.jsx"
click node_workspace_data "https://github.com/saber20005/cybertrace/blob/main/src/data/investigationWorkspace.js"
click node_report "https://github.com/saber20005/cybertrace/blob/main/src/utils/investigationReport.js"
click node_recommendations "https://github.com/saber20005/cybertrace/blob/main/src/utils/learningPlan.js"
click node_soc_page "https://github.com/saber20005/cybertrace/blob/main/src/pages/SocShift.jsx"
click node_soc_catalog "https://github.com/saber20005/cybertrace/blob/main/src/data/socShiftCatalog.js"
click node_soc_session "https://github.com/saber20005/cybertrace/blob/main/src/utils/socShiftSession.js"
click node_verified_soc "https://github.com/saber20005/cybertrace/blob/main/src/pages/VerifiedSoc.jsx"
click node_verified_backend "https://github.com/saber20005/cybertrace/blob/main/src/blackbox/verifiedSocBackend.js"
click node_progress "https://github.com/saber20005/cybertrace/blob/main/src/utils/caseProgress.js"
click node_xp "https://github.com/saber20005/cybertrace/blob/main/src/utils/xp.js"
click node_cloud "https://github.com/saber20005/cybertrace/blob/main/src/utils/cloudProgress.js"
click node_firebase "https://github.com/saber20005/cybertrace/blob/main/src/firebase.js"
click node_auth "https://github.com/saber20005/cybertrace/blob/main/src/pages/Auth.jsx"
click node_blackbox_provider "https://github.com/saber20005/cybertrace/blob/main/src/blackbox/BlackBoxProvider.jsx"
click node_blackbox_controller "https://github.com/saber20005/cybertrace/blob/main/src/blackbox/controller.js"
click node_blackbox_backend "https://github.com/saber20005/cybertrace/blob/main/src/blackbox/backend.js"
click node_blackbox_link "https://github.com/saber20005/cybertrace/blob/main/src/blackbox/BlackBoxLink.jsx"
click node_pro "https://github.com/saber20005/cybertrace/blob/main/src/pages/Pro.jsx"

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_pro toneBlue
class node_library,node_catalog,node_case_data,node_investigation,node_workspace,node_workspace_data,node_report,node_recommendations,node_blackbox_service toneAmber
class node_soc_page,node_soc_catalog,node_soc_session,node_verified_soc,node_verified_backend toneMint
class node_progress,node_xp,node_cloud,node_local_store,node_firebase,node_auth toneRose
class node_blackbox_provider,node_blackbox_controller,node_blackbox_backend,node_blackbox_link,node_learner toneIndigo
```

## Components

### Application flow

- [App router](https://github.com/saber20005/cybertrace/blob/main/src/App.jsx): `src/App.jsx`
- [Pro roadmap](https://github.com/saber20005/cybertrace/blob/main/src/pages/Pro.jsx): `src/pages/Pro.jsx`

### Incident investigations

- [Case library](https://github.com/saber20005/cybertrace/blob/main/src/pages/InvestigationLibrary.jsx): `src/pages/InvestigationLibrary.jsx`
- [Case catalog](https://github.com/saber20005/cybertrace/blob/main/src/data/caseCatalog.js): `src/data/caseCatalog.js`
- [Investigation cases](https://github.com/saber20005/cybertrace/blob/main/src/data/cases.js): `src/data/cases.js`
- [Case workflow](https://github.com/saber20005/cybertrace/blob/main/src/pages/Investigation.jsx): `src/pages/Investigation.jsx`
- [Evidence workspace](https://github.com/saber20005/cybertrace/blob/main/src/components/InvestigationWorkspace.jsx): `src/components/InvestigationWorkspace.jsx`
- [Workspace evidence](https://github.com/saber20005/cybertrace/blob/main/src/data/investigationWorkspace.js): `src/data/investigationWorkspace.js`
- [Review and report](https://github.com/saber20005/cybertrace/blob/main/src/utils/investigationReport.js): `src/utils/investigationReport.js`
- [Learning recommendations](https://github.com/saber20005/cybertrace/blob/main/src/utils/learningPlan.js): `src/utils/learningPlan.js`

### SOC training

- [SOC shift](https://github.com/saber20005/cybertrace/blob/main/src/pages/SocShift.jsx): `src/pages/SocShift.jsx`
- [Shift and alert catalog](https://github.com/saber20005/cybertrace/blob/main/src/data/socShiftCatalog.js): `src/data/socShiftCatalog.js`
- [Triage session scoring](https://github.com/saber20005/cybertrace/blob/main/src/utils/socShiftSession.js): `src/utils/socShiftSession.js`
- [Verified SOC assessment](https://github.com/saber20005/cybertrace/blob/main/src/pages/VerifiedSoc.jsx): `src/pages/VerifiedSoc.jsx`
- [Verified SOC service](https://github.com/saber20005/cybertrace/blob/main/src/blackbox/verifiedSocBackend.js): `src/blackbox/verifiedSocBackend.js`

### Progress and identity

- [Case progress records](https://github.com/saber20005/cybertrace/blob/main/src/utils/caseProgress.js): `src/utils/caseProgress.js`
- [XP and levels](https://github.com/saber20005/cybertrace/blob/main/src/utils/xp.js): `src/utils/xp.js`
- [Cloud progress sync](https://github.com/saber20005/cybertrace/blob/main/src/utils/cloudProgress.js): `src/utils/cloudProgress.js`
- **Browser storage**
- [Firebase auth and data](https://github.com/saber20005/cybertrace/blob/main/src/firebase.js): `src/firebase.js`
- [Account access](https://github.com/saber20005/cybertrace/blob/main/src/pages/Auth.jsx): `src/pages/Auth.jsx`

### BLACKBOX integration

- [BLACKBOX provider](https://github.com/saber20005/cybertrace/blob/main/src/blackbox/BlackBoxProvider.jsx): `src/blackbox/BlackBoxProvider.jsx`
- [Result sync controller](https://github.com/saber20005/cybertrace/blob/main/src/blackbox/controller.js): `src/blackbox/controller.js`
- [BLACKBOX backend](https://github.com/saber20005/cybertrace/blob/main/src/blackbox/backend.js): `src/blackbox/backend.js`
- [Learning link and account](https://github.com/saber20005/cybertrace/blob/main/src/blackbox/BlackBoxLink.jsx): `src/blackbox/BlackBoxLink.jsx`

### Other components

- **Learner**
- **BLACKBOX service**

## Connections

- Learner → App router: opens (evidence: `README.md`)
- App router → Case library: routes to (evidence: `src/App.jsx`)
- App router → Case workflow: routes to (evidence: `src/App.jsx`)
- App router → SOC shift: routes to (evidence: `src/App.jsx`)
- App router → Verified SOC assessment: routes to (evidence: `src/App.jsx`)
- App router → Account access: routes to (evidence: `src/App.jsx`)
- App router → Pro roadmap: routes to (evidence: `src/App.jsx`)
- Case library → Case catalog: reads (evidence: `src/pages/InvestigationLibrary.jsx`)
- Case catalog → Investigation cases: loads cases (evidence: `src/data/cases.js`)
- Case library → Case progress records: reads progress (evidence: `src/pages/InvestigationLibrary.jsx`)
- Case library → Learning recommendations: gets guidance (evidence: `src/pages/InvestigationLibrary.jsx`)
- Case workflow → Case catalog: gets case details (evidence: `src/pages/Investigation.jsx`)
- Case workflow → Evidence workspace: renders (evidence: `src/pages/Investigation.jsx`)
- Evidence workspace → Workspace evidence: loads evidence (evidence: `src/components/InvestigationWorkspace.jsx`)
- Case workflow → Case progress records: records result (evidence: `src/pages/Investigation.jsx`)
- Case workflow → XP and levels: awards XP (evidence: `src/pages/Investigation.jsx`)
- Case workflow → Review and report: creates report (evidence: `src/pages/Investigation.jsx`)
- SOC shift → Shift and alert catalog: loads shift (evidence: `src/pages/SocShift.jsx`)
- SOC shift → Triage session scoring: uses session (evidence: `src/pages/SocShift.jsx`)
- Triage session scoring → Shift and alert catalog: grades alerts (evidence: `src/utils/socShiftSession.js`)
- Triage session scoring → Browser storage: reads and writes (evidence: `src/utils/socShiftSession.js`)
- Verified SOC assessment → Verified SOC service: requests assessment (evidence: `src/pages/VerifiedSoc.jsx`)
- Verified SOC service → BLACKBOX service: uses service
- Case progress records → Browser storage: reads and writes (evidence: `src/utils/caseProgress.js`)
- XP and levels → Browser storage: persists XP (evidence: `src/utils/xp.js`)
- App router → Cloud progress sync: checks sync (evidence: `src/App.jsx`)
- Cloud progress sync → Firebase auth and data: syncs through (evidence: `src/utils/cloudProgress.js`)
- Account access → Firebase auth and data: authenticates (evidence: `src/pages/Auth.jsx`)
- BLACKBOX provider → Result sync controller: provides controller (evidence: `src/blackbox/BlackBoxProvider.jsx`)
- Result sync controller → BLACKBOX backend: creates backend (evidence: `src/blackbox/controller.js`)
- BLACKBOX backend → BLACKBOX service: connects to
- Case workflow → BLACKBOX provider: uses account context (evidence: `src/pages/Investigation.jsx`)
- Case workflow → Learning link and account: offers lab link
- Account access → Learning link and account: shows linking control (evidence: `src/pages/Auth.jsx`)
