# iqbalthehitchhiker/netwatch architecture

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

- Interactive diagram: https://gitdiagram.com/iqbalthehitchhiker/netwatch
- Repository: https://github.com/iqbalthehitchhiker/netwatch

## Overview

NetWatch is a browser-based network-incident learning simulator with student quiz and instructor teaching/management modes. Learners select a lesson, observe a simulated incident through network and telemetry views, then answer a diagnosis; quiz results and attempt data are handled by an Express/SQLite backend. The graph preserves the lesson, simulation, explanation, self-check, authentication, results, and instructor-management capabilities. Source excerpts show the frontend controller’s renderer calls and backend route wiring; the README is empty, and the excerpts do not establish the browser API’s HTTP connections to the backend.

Main entry points: [`src/app.js`](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/app.js) (Application controller), [`backend/server.js`](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/server.js) (Express server), [`backend/db.js`](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/db.js) (SQLite records), [`backend/routes/results.js`](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/results.js) (Results routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning content"]
  node_lessons["Lessons and incidents<br/>[lessons.js]"]
  node_explain["Explanation content<br/>[explain-content.js]"]
  node_bridge["Explanation bridge"]
  node_scoring["Quiz scoring<br/>[scoring.js]"]
end

subgraph group_simulation["Simulation experience"]
  node_engine["Simulation engine<br/>[engine.js]"]
  node_selfcheck["Self-check mode<br/>[self-check.js]"]
  node_overview["Overview renderer<br/>[overview.js]"]
  node_topology["Topology renderer<br/>[topology.js]"]
  node_alerts["Alerts renderer<br/>[alerts.js]"]
  node_charts["Charts renderer<br/>[charts.js]"]
  node_packets["Packet renderer<br/>[packets.js]"]
  node_logs["Logs renderer<br/>[logs.js]"]
end

subgraph group_frontend["Frontend coordination"]
  node_app["Application controller<br/>[app.js]"]
  node_session["Session state<br/>[auth.js]"]
  node_api["Frontend API<br/>[api.js]"]
end

subgraph group_backend["Accounts and records"]
  node_server["Express server<br/>[server.js]"]
  node_authroute["Login route<br/>[auth.js]"]
  node_attempts["Attempt routes<br/>[attempts.js]"]
  node_results["Results routes<br/>[results.js]"]
  node_admin["Instructor routes<br/>[admin.js]"]
  node_middleware["JWT authorization<br/>[auth.js]"]
  node_database[("SQLite records<br/>[db.js]")]
end

node_learner(("Learner / instructor"))

node_learner -.->|"uses"| node_app
node_app -->|"loads lesson data"| node_lessons
node_app -->|"uses explanations"| node_explain
node_bridge -->|"accesses content"| node_explain
node_app -->|"uses scoring"| node_scoring
node_app -->|"controls simulation"| node_engine
node_engine -->|"loads configuration"| node_lessons
node_app -->|"controls self-check"| node_selfcheck
node_app -->|"renders overview"| node_overview
node_app -->|"renders topology"| node_topology
node_app -->|"renders alerts"| node_alerts
node_app -->|"updates charts"| node_charts
node_app -->|"renders packets"| node_packets
node_app -->|"renders logs"| node_logs
node_app -->|"reads and clears session"| node_session
node_app -->|"uses API"| node_api
node_server -->|"routes requests"| node_authroute
node_server -->|"routes requests"| node_attempts
node_server -->|"routes requests"| node_results
node_server -->|"routes requests"| node_admin
node_authroute -->|"looks up accounts"| node_database
node_attempts -->|"reads and updates attempts"| node_database
node_results -->|"checks role"| node_middleware
node_results -->|"records and reads results"| node_database
node_admin -->|"checks instructor role"| node_middleware
node_admin -->|"manages student records"| node_database

click node_app "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/app.js"
click node_lessons "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/lessons.js"
click node_explain "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/explain-content.js"
click node_bridge "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/explain-content-bridge.js"
click node_scoring "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/scoring.js"
click node_engine "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/engine.js"
click node_selfcheck "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/self-check.js"
click node_overview "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/overview.js"
click node_topology "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/topology.js"
click node_alerts "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/alerts.js"
click node_charts "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/charts.js"
click node_packets "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/packets.js"
click node_logs "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/logs.js"
click node_session "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/auth.js"
click node_api "https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/api.js"
click node_server "https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/server.js"
click node_authroute "https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/auth.js"
click node_attempts "https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/attempts.js"
click node_results "https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/results.js"
click node_admin "https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/admin.js"
click node_middleware "https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/middleware/auth.js"
click node_database "https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/db.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_lessons,node_explain,node_bridge,node_scoring toneBlue
class node_engine,node_selfcheck,node_overview,node_topology,node_alerts,node_charts,node_packets,node_logs toneAmber
class node_app,node_session,node_api toneMint
class node_server,node_authroute,node_attempts,node_results,node_admin,node_middleware,node_database toneRose
class node_learner toneIndigo
```

## Components

### Learning content

- [Lessons and incidents](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/lessons.js): `src/lessons.js`
- [Explanation content](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/explain-content.js): `src/explain-content.js`
- [Explanation bridge](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/explain-content-bridge.js): `src/explain-content-bridge.js`
- [Quiz scoring](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/scoring.js): `src/scoring.js`

### Simulation experience

- [Simulation engine](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/engine.js): `src/engine.js`
- [Self-check mode](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/self-check.js): `src/self-check.js`
- [Overview renderer](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/overview.js): `src/renderers/overview.js`
- [Topology renderer](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/topology.js): `src/renderers/topology.js`
- [Alerts renderer](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/alerts.js): `src/renderers/alerts.js`
- [Charts renderer](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/charts.js): `src/renderers/charts.js`
- [Packet renderer](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/packets.js): `src/renderers/packets.js`
- [Logs renderer](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/renderers/logs.js): `src/renderers/logs.js`

### Frontend coordination

- [Application controller](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/app.js): `src/app.js`
- [Session state](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/auth.js): `src/auth.js`
- [Frontend API](https://github.com/iqbalthehitchhiker/netwatch/blob/main/src/api.js): `src/api.js`

### Accounts and records

- [Express server](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/server.js): `backend/server.js`
- [Login route](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Attempt routes](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/attempts.js): `backend/routes/attempts.js`
- [Results routes](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/results.js): `backend/routes/results.js`
- [Instructor routes](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/routes/admin.js): `backend/routes/admin.js`
- [JWT authorization](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`
- [SQLite records](https://github.com/iqbalthehitchhiker/netwatch/blob/main/backend/db.js): `backend/db.js`

### Other components

- **Learner / instructor**

## Connections

- Learner / instructor → Application controller: uses
- Application controller → Lessons and incidents: loads lesson data (evidence: `src/app.js`)
- Application controller → Explanation content: uses explanations (evidence: `src/app.js`)
- Explanation bridge → Explanation content: accesses content (evidence: `src/explain-content-bridge.js`)
- Application controller → Quiz scoring: uses scoring (evidence: `src/app.js`)
- Application controller → Simulation engine: controls simulation (evidence: `src/app.js`)
- Simulation engine → Lessons and incidents: loads configuration (evidence: `src/engine.js`)
- Application controller → Self-check mode: controls self-check (evidence: `src/app.js`)
- Application controller → Overview renderer: renders overview (evidence: `src/app.js`)
- Application controller → Topology renderer: renders topology (evidence: `src/app.js`)
- Application controller → Alerts renderer: renders alerts (evidence: `src/app.js`)
- Application controller → Charts renderer: updates charts (evidence: `src/app.js`)
- Application controller → Packet renderer: renders packets (evidence: `src/app.js`)
- Application controller → Logs renderer: renders logs (evidence: `src/app.js`)
- Application controller → Session state: reads and clears session (evidence: `src/app.js`)
- Application controller → Frontend API: uses API (evidence: `src/app.js`)
- Express server → Login route: routes requests (evidence: `backend/server.js`)
- Express server → Attempt routes: routes requests (evidence: `backend/server.js`)
- Express server → Results routes: routes requests (evidence: `backend/server.js`)
- Express server → Instructor routes: routes requests (evidence: `backend/server.js`)
- Login route → SQLite records: looks up accounts (evidence: `backend/routes/auth.js`)
- Attempt routes → SQLite records: reads and updates attempts (evidence: `backend/routes/attempts.js`)
- Results routes → JWT authorization: checks role (evidence: `backend/routes/results.js`)
- Results routes → SQLite records: records and reads results (evidence: `backend/routes/results.js`)
- Instructor routes → JWT authorization: checks instructor role (evidence: `backend/routes/admin.js`)
- Instructor routes → SQLite records: manages student records (evidence: `backend/routes/admin.js`)