# hmug12/openclass-box architecture

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

- Interactive diagram: https://gitdiagram.com/hmug12/openclass-box
- Repository: https://github.com/hmug12/openclass-box

## Overview

OpenClass-Box is a portable Windows classroom-device operations toolkit. A staff member uses its React interface to inspect a machine, run classroom checks or repairs, and manage tools; the frontend calls Python through the documented API boundary. A separate LAN workflow pairs A/B devices so the teacher machine can issue jobs and transfer files. The map also preserves documented security, media, scheduling, plugin, knowledge-base, and remote-Web capabilities. Some subsystem links are README-documented because their implementation was not sampled; those limits are reflected by omitting uncertain internal calls.

Main entry points: [`backend/api.py`](https://github.com/hmug12/openclass-box/blob/main/backend/api.py) (Python API), [`backend/core/remote_admin.py`](https://github.com/hmug12/openclass-box/blob/main/backend/core/remote_admin.py) (Remote admin Web), [`backend/net/server.py`](https://github.com/hmug12/openclass-box/blob/main/backend/net/server.py) (Teacher LAN server), [`backend/net/client.py`](https://github.com/hmug12/openclass-box/blob/main/backend/net/client.py) (Managed-device client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_desktop["React interface<br/>[App.tsx]"]
  node_bridge["Frontend API<br/>[api.ts]"]
  node_pythonapi["Python API<br/>[api.py]"]
end

subgraph group_operations["Device operations"]
  node_monitor["System monitoring<br/>[monitor.py]"]
  node_hardware["Hardware details<br/>[hardware_detail.py]"]
  node_classroom["Classroom checks<br/>[classroom.py]"]
  node_health["Health checks<br/>[health.py]"]
  node_preflight["Preflight checks<br/>[preflight.py]"]
  node_results["Diagnostic results<br/>[diag_result.py]"]
  node_repair["Repair actions<br/>[repair.py]"]
end

subgraph group_collaboration["LAN and remote management"]
  node_lanclient["Managed-device client<br/>[client.py]"]
  node_lanserver["Teacher LAN server<br/>[server.py]"]
  node_protocol["LAN protocol<br/>[proto.py]"]
  node_discovery["LAN discovery<br/>[discovery.py]"]
  node_remote["Remote admin Web<br/>[remote_admin.py]"]
  node_tunnel["Tunneling<br/>[tunnel.py]"]
  node_webconsole["Phone Web console<br/>[webconsole.py]"]
end

subgraph group_capabilities["Tools and user features"]
  node_tools["Tool registry<br/>[registry.py]"]
  node_market["Plugin market<br/>[market.py]"]
  node_security["Security monitoring<br/>[security.py]"]
  node_tasks["Scheduled tasks<br/>[tasks.py]"]
  node_music["Music playback<br/>[music.py]"]
  node_wallpaper["Wallpaper manager<br/>[wallpaper.py]"]
  node_knowledge["Compatibility knowledge<br/>[kb.py]"]
  node_chat["Temporary transfer<br/>[chat.py]"]
end

subgraph group_foundation["Runtime foundation"]
  node_host["Desktop host<br/>[main.py]"]
  node_config[("Configuration<br/>[config.py]")]
  node_paths["Data paths<br/>[paths.py]"]
  node_logs["Application logging<br/>[applog.py]"]
end

node_staff(("Staff user"))

node_staff -->|"uses"| node_desktop
node_desktop -->|"calls"| node_bridge
node_bridge -->|"invokes"| node_pythonapi
node_host -->|"hosts"| node_pythonapi
node_pythonapi -->|"reads metrics"| node_monitor
node_pythonapi -->|"reads details"| node_hardware
node_pythonapi -->|"runs checks"| node_health
node_pythonapi -->|"runs checks"| node_classroom
node_pythonapi -->|"runs checks"| node_preflight
node_health -->|"normalizes"| node_results
node_pythonapi -->|"runs repair"| node_repair
node_pythonapi -->|"starts server"| node_lanserver
node_lanclient -->|"discovers server"| node_discovery
node_lanclient -->|"exchanges messages"| node_protocol
node_lanserver -->|"uses protocol"| node_protocol
node_remote -->|"manages devices"| node_lanserver
node_remote -->|"checks tunnel"| node_tunnel
node_pythonapi -->|"controls service"| node_remote
node_pythonapi -->|"serves console"| node_webconsole
node_pythonapi -->|"launches tools"| node_tools
node_pythonapi -->|"manages plugins"| node_market
node_pythonapi -->|"exposes controls"| node_security
node_pythonapi -->|"exposes tasks"| node_tasks
node_pythonapi -.->|"exposes playback"| node_music
node_pythonapi -.->|"exposes wallpaper"| node_wallpaper
node_pythonapi -.->|"exposes knowledge"| node_knowledge
node_pythonapi -.->|"exposes transfer"| node_chat
node_config -->|"stores under"| node_paths
node_logs -->|"writes under"| node_paths
node_host -->|"installs logging"| node_logs

click node_desktop "https://github.com/hmug12/openclass-box/blob/main/frontend/src/App.tsx"
click node_bridge "https://github.com/hmug12/openclass-box/blob/main/frontend/src/api.ts"
click node_pythonapi "https://github.com/hmug12/openclass-box/blob/main/backend/api.py"
click node_host "https://github.com/hmug12/openclass-box/blob/main/backend/main.py"
click node_monitor "https://github.com/hmug12/openclass-box/blob/main/backend/core/monitor.py"
click node_hardware "https://github.com/hmug12/openclass-box/blob/main/backend/core/hardware_detail.py"
click node_classroom "https://github.com/hmug12/openclass-box/blob/main/backend/core/classroom.py"
click node_health "https://github.com/hmug12/openclass-box/blob/main/backend/core/health.py"
click node_preflight "https://github.com/hmug12/openclass-box/blob/main/backend/core/preflight.py"
click node_results "https://github.com/hmug12/openclass-box/blob/main/backend/core/diag_result.py"
click node_repair "https://github.com/hmug12/openclass-box/blob/main/backend/core/repair.py"
click node_lanclient "https://github.com/hmug12/openclass-box/blob/main/backend/net/client.py"
click node_lanserver "https://github.com/hmug12/openclass-box/blob/main/backend/net/server.py"
click node_protocol "https://github.com/hmug12/openclass-box/blob/main/backend/net/proto.py"
click node_discovery "https://github.com/hmug12/openclass-box/blob/main/backend/net/discovery.py"
click node_remote "https://github.com/hmug12/openclass-box/blob/main/backend/core/remote_admin.py"
click node_tunnel "https://github.com/hmug12/openclass-box/blob/main/backend/core/tunnel.py"
click node_webconsole "https://github.com/hmug12/openclass-box/blob/main/backend/core/webconsole.py"
click node_tools "https://github.com/hmug12/openclass-box/blob/main/backend/core/registry.py"
click node_market "https://github.com/hmug12/openclass-box/blob/main/backend/core/market.py"
click node_security "https://github.com/hmug12/openclass-box/blob/main/backend/core/security.py"
click node_tasks "https://github.com/hmug12/openclass-box/blob/main/backend/core/tasks.py"
click node_music "https://github.com/hmug12/openclass-box/blob/main/backend/core/music.py"
click node_wallpaper "https://github.com/hmug12/openclass-box/blob/main/backend/core/wallpaper.py"
click node_knowledge "https://github.com/hmug12/openclass-box/blob/main/backend/core/kb.py"
click node_chat "https://github.com/hmug12/openclass-box/blob/main/backend/core/chat.py"
click node_config "https://github.com/hmug12/openclass-box/blob/main/backend/core/config.py"
click node_paths "https://github.com/hmug12/openclass-box/blob/main/backend/core/paths.py"
click node_logs "https://github.com/hmug12/openclass-box/blob/main/backend/core/applog.py"

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_desktop,node_bridge,node_pythonapi,node_staff toneBlue
class node_monitor,node_hardware,node_classroom,node_health,node_preflight,node_results,node_repair toneAmber
class node_lanclient,node_lanserver,node_protocol,node_discovery,node_remote,node_tunnel,node_webconsole toneMint
class node_tools,node_market,node_security,node_tasks,node_music,node_wallpaper,node_knowledge,node_chat toneRose
class node_host,node_config,node_paths,node_logs toneIndigo
```

## Components

### Desktop interface

- [React interface](https://github.com/hmug12/openclass-box/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Frontend API](https://github.com/hmug12/openclass-box/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Python API](https://github.com/hmug12/openclass-box/blob/main/backend/api.py): `backend/api.py`

### Device operations

- [System monitoring](https://github.com/hmug12/openclass-box/blob/main/backend/core/monitor.py): `backend/core/monitor.py`
- [Hardware details](https://github.com/hmug12/openclass-box/blob/main/backend/core/hardware_detail.py): `backend/core/hardware_detail.py`
- [Classroom checks](https://github.com/hmug12/openclass-box/blob/main/backend/core/classroom.py): `backend/core/classroom.py`
- [Health checks](https://github.com/hmug12/openclass-box/blob/main/backend/core/health.py): `backend/core/health.py`
- [Preflight checks](https://github.com/hmug12/openclass-box/blob/main/backend/core/preflight.py): `backend/core/preflight.py`
- [Diagnostic results](https://github.com/hmug12/openclass-box/blob/main/backend/core/diag_result.py): `backend/core/diag_result.py`
- [Repair actions](https://github.com/hmug12/openclass-box/blob/main/backend/core/repair.py): `backend/core/repair.py`

### LAN and remote management

- [Managed-device client](https://github.com/hmug12/openclass-box/blob/main/backend/net/client.py): `backend/net/client.py`
- [Teacher LAN server](https://github.com/hmug12/openclass-box/blob/main/backend/net/server.py): `backend/net/server.py`
- [LAN protocol](https://github.com/hmug12/openclass-box/blob/main/backend/net/proto.py): `backend/net/proto.py`
- [LAN discovery](https://github.com/hmug12/openclass-box/blob/main/backend/net/discovery.py): `backend/net/discovery.py`
- [Remote admin Web](https://github.com/hmug12/openclass-box/blob/main/backend/core/remote_admin.py): `backend/core/remote_admin.py`
- [Tunneling](https://github.com/hmug12/openclass-box/blob/main/backend/core/tunnel.py): `backend/core/tunnel.py`
- [Phone Web console](https://github.com/hmug12/openclass-box/blob/main/backend/core/webconsole.py): `backend/core/webconsole.py`

### Tools and user features

- [Tool registry](https://github.com/hmug12/openclass-box/blob/main/backend/core/registry.py): `backend/core/registry.py`
- [Plugin market](https://github.com/hmug12/openclass-box/blob/main/backend/core/market.py): `backend/core/market.py`
- [Security monitoring](https://github.com/hmug12/openclass-box/blob/main/backend/core/security.py): `backend/core/security.py`
- [Scheduled tasks](https://github.com/hmug12/openclass-box/blob/main/backend/core/tasks.py): `backend/core/tasks.py`
- [Music playback](https://github.com/hmug12/openclass-box/blob/main/backend/core/music.py): `backend/core/music.py`
- [Wallpaper manager](https://github.com/hmug12/openclass-box/blob/main/backend/core/wallpaper.py): `backend/core/wallpaper.py`
- [Compatibility knowledge](https://github.com/hmug12/openclass-box/blob/main/backend/core/kb.py): `backend/core/kb.py`
- [Temporary transfer](https://github.com/hmug12/openclass-box/blob/main/backend/core/chat.py): `backend/core/chat.py`

### Runtime foundation

- [Desktop host](https://github.com/hmug12/openclass-box/blob/main/backend/main.py): `backend/main.py`
- [Configuration](https://github.com/hmug12/openclass-box/blob/main/backend/core/config.py): `backend/core/config.py`
- [Data paths](https://github.com/hmug12/openclass-box/blob/main/backend/core/paths.py): `backend/core/paths.py`
- [Application logging](https://github.com/hmug12/openclass-box/blob/main/backend/core/applog.py): `backend/core/applog.py`

### Other components

- **Staff user**

## Connections

- Staff user → React interface: uses (evidence: `README.md`)
- React interface → Frontend API: calls (evidence: `frontend/src/App.tsx`)
- Frontend API → Python API: invokes (evidence: `README.md`)
- Desktop host → Python API: hosts (evidence: `backend/main.py`)
- Python API → System monitoring: reads metrics (evidence: `backend/api.py`)
- Python API → Hardware details: reads details (evidence: `backend/api.py`)
- Python API → Health checks: runs checks (evidence: `backend/api.py`)
- Python API → Classroom checks: runs checks (evidence: `backend/api.py`)
- Python API → Preflight checks: runs checks (evidence: `backend/api.py`)
- Health checks → Diagnostic results: normalizes (evidence: `backend/core/health.py`)
- Python API → Repair actions: runs repair (evidence: `backend/api.py`)
- Python API → Teacher LAN server: starts server (evidence: `backend/api.py`)
- Managed-device client → LAN discovery: discovers server (evidence: `backend/net/client.py`)
- Managed-device client → LAN protocol: exchanges messages (evidence: `backend/net/client.py`)
- Teacher LAN server → LAN protocol: uses protocol (evidence: `backend/net/server.py`)
- Remote admin Web → Teacher LAN server: manages devices (evidence: `backend/core/remote_admin.py`)
- Remote admin Web → Tunneling: checks tunnel (evidence: `backend/core/remote_admin.py`)
- Python API → Remote admin Web: controls service (evidence: `backend/api.py`)
- Python API → Phone Web console: serves console (evidence: `backend/api.py`)
- Python API → Tool registry: launches tools (evidence: `backend/api.py`)
- Python API → Plugin market: manages plugins (evidence: `backend/api.py`)
- Python API → Security monitoring: exposes controls (evidence: `backend/api.py`)
- Python API → Scheduled tasks: exposes tasks (evidence: `backend/api.py`)
- Python API → Music playback: exposes playback (evidence: `README.md`)
- Python API → Wallpaper manager: exposes wallpaper (evidence: `README.md`)
- Python API → Compatibility knowledge: exposes knowledge (evidence: `README.md`)
- Python API → Temporary transfer: exposes transfer (evidence: `README.md`)
- Configuration → Data paths: stores under (evidence: `backend/core/config.py`)
- Application logging → Data paths: writes under (evidence: `backend/core/applog.py`)
- Desktop host → Application logging: installs logging (evidence: `backend/main.py`)
