# charlymigenes-ux/nopal architecture

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

- Interactive diagram: https://gitdiagram.com/charlymigenes-ux/nopal
- Repository: https://github.com/charlymigenes-ux/nopal

## Overview

NOPAL is a self-hosted workshop control panel. A browser user enters through the FastAPI application, then uses its dashboard and APIs to monitor or control printers and GRBL machines, or to manage and preview model/G-code files. Distinct branches provide brand-specific printer drivers, laser/CNC control, plugins, AI, and the TUNA-Screen mobile API. Edges are limited to relationships shown in excerpts, the source index, or README; several README-described subsystems have directory-level paths because their implementation was not sampled.

Main entry points: [`backend/main.py`](https://github.com/charlymigenes-ux/nopal/blob/main/backend/main.py) (FastAPI application), [`backend/services/dashboard_service.py`](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/dashboard_service.py) (Workshop status), [`backend/services/tunascreen_service.py`](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/tunascreen_service.py) (TUNA device facade), [`backend/static/js/app.js`](https://github.com/charlymigenes-ux/nopal/blob/main/backend/static/js/app.js) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application and access"]
  node_browser["Browser UI<br/>[app.js]"]
  node_server["FastAPI application<br/>[main.py]"]
  node_auth_api["Login API<br/>[auth.py]"]
  node_auth[("Accounts and sessions<br/>[auth_service.py]")]
  node_authorization["Access policy"]
end

subgraph group_machines["Machine operations"]
  node_dashboard_api["Dashboard API<br/>[status.py]"]
  node_dashboard["Workshop status"]
  node_klipper["Klipper / Moonraker<br/>[klipper_service.py]"]
  node_marlin_api["Marlin API<br/>[marlin_printers.py]"]
  node_marlin["Marlin driver"]
  node_bambu["Bambu driver<br/>[bambu_service.py]"]
  node_elegoo["Elegoo driver<br/>[elegoo_service.py]"]
  node_flashforge["FlashForge driver"]
  node_laser_api["Laser / CNC API<br/>[laser.py]"]
  node_laser["GRBL control<br/>[laser_service.py]"]
end

subgraph group_library["Model and G-code library"]
  node_assets_api["Library and upload API<br/>[upload.py]"]
  node_files[("Model and G-code files<br/>[file_service.py]")]
  node_preview["3D / toolpath preview<br/>[viewer.js]"]
end

subgraph group_extensions["Plugins and AI"]
  node_plugins["Plugin loading"]
  node_ai_api["AI API<br/>[ai.py]"]
  node_ai_agent["AI agent and tools<br/>[ai_agent.py]"]
end

subgraph group_mobile["TUNA-Screen"]
  node_tuna_api["TUNA-Screen API<br/>[tunascreen.py]"]
  node_tuna["TUNA device facade"]
  node_tuna_client["TUNA-Screen client"]
end

node_user(("Workshop user"))

node_user -->|"uses"| node_browser
node_browser -->|"requests"| node_server
node_server -->|"routes"| node_dashboard_api
node_server -->|"routes"| node_assets_api
node_server -->|"routes"| node_laser_api
node_server -->|"routes"| node_auth_api
node_auth_api -->|"calls"| node_auth
node_server -->|"loads"| node_plugins
node_dashboard_api -->|"calls"| node_dashboard
node_dashboard -->|"queries"| node_klipper
node_dashboard -->|"queries"| node_marlin
node_dashboard -->|"queries"| node_bambu
node_dashboard -->|"queries"| node_elegoo
node_dashboard -->|"queries"| node_flashforge
node_dashboard -->|"queries"| node_laser
node_marlin_api -->|"calls"| node_marlin
node_laser_api -->|"calls"| node_laser
node_server -->|"enforces"| node_authorization
node_assets_api -.->|"manages"| node_files
node_browser -->|"previews files"| node_preview
node_server -->|"routes"| node_ai_api
node_ai_api -->|"delegates"| node_ai_agent
node_server -->|"routes"| node_tuna_api
node_tuna_client -->|"requests"| node_tuna_api
node_tuna_api -->|"calls"| node_tuna
node_tuna -->|"delegates"| node_klipper
node_tuna -->|"delegates"| node_marlin
node_tuna -->|"delegates"| node_bambu
node_tuna -->|"delegates"| node_elegoo
node_tuna -->|"delegates"| node_flashforge
node_tuna -->|"delegates"| node_laser

click node_browser "https://github.com/charlymigenes-ux/nopal/blob/main/backend/static/js/app.js"
click node_server "https://github.com/charlymigenes-ux/nopal/blob/main/backend/main.py"
click node_auth_api "https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/auth.py"
click node_auth "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/auth_service.py"
click node_authorization "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/authorization_policy.py"
click node_dashboard_api "https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/status.py"
click node_dashboard "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/dashboard_service.py"
click node_klipper "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/klipper_service.py"
click node_marlin_api "https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/marlin_printers.py"
click node_marlin "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/marlin_printer_service.py"
click node_bambu "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/bambu_service.py"
click node_elegoo "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/elegoo_service.py"
click node_flashforge "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/flashforge_service.py"
click node_laser_api "https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/laser.py"
click node_laser "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/laser_service.py"
click node_assets_api "https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/upload.py"
click node_files "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/file_service.py"
click node_preview "https://github.com/charlymigenes-ux/nopal/blob/main/backend/static/js/visor/viewer.js"
click node_plugins "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/plugin_loader_service.py"
click node_ai_api "https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/ai.py"
click node_ai_agent "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/ai_agent.py"
click node_tuna_api "https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/tunascreen.py"
click node_tuna "https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/tunascreen_service.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_browser,node_server,node_auth_api,node_auth,node_authorization,node_user toneBlue
class node_dashboard_api,node_dashboard,node_klipper,node_marlin_api,node_marlin,node_bambu,node_elegoo,node_flashforge,node_laser_api,node_laser toneAmber
class node_assets_api,node_files,node_preview toneMint
class node_plugins,node_ai_api,node_ai_agent toneRose
class node_tuna_api,node_tuna,node_tuna_client toneIndigo
```

## Components

### Application and access

- [Browser UI](https://github.com/charlymigenes-ux/nopal/blob/main/backend/static/js/app.js): `backend/static/js/app.js`
- [FastAPI application](https://github.com/charlymigenes-ux/nopal/blob/main/backend/main.py): `backend/main.py`
- [Login API](https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [Accounts and sessions](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Access policy](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/authorization_policy.py): `backend/services/authorization_policy.py`

### Machine operations

- [Dashboard API](https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/status.py): `backend/api/status.py`
- [Workshop status](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/dashboard_service.py): `backend/services/dashboard_service.py`
- [Klipper / Moonraker](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/klipper_service.py): `backend/services/klipper_service.py`
- [Marlin API](https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/marlin_printers.py): `backend/api/marlin_printers.py`
- [Marlin driver](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/marlin_printer_service.py): `backend/services/marlin_printer_service.py`
- [Bambu driver](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/bambu_service.py): `backend/services/bambu_service.py`
- [Elegoo driver](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/elegoo_service.py): `backend/services/elegoo_service.py`
- [FlashForge driver](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/flashforge_service.py): `backend/services/flashforge_service.py`
- [Laser / CNC API](https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/laser.py): `backend/api/laser.py`
- [GRBL control](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/laser_service.py): `backend/services/laser_service.py`

### Model and G-code library

- [Library and upload API](https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/upload.py): `backend/api/upload.py`
- [Model and G-code files](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/file_service.py): `backend/services/file_service.py`
- [3D / toolpath preview](https://github.com/charlymigenes-ux/nopal/blob/main/backend/static/js/visor/viewer.js): `backend/static/js/visor/viewer.js`

### Plugins and AI

- [Plugin loading](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/plugin_loader_service.py): `backend/services/plugin_loader_service.py`
- [AI API](https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/ai.py): `backend/api/ai.py`
- [AI agent and tools](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/ai_agent.py): `backend/services/ai_agent.py`

### TUNA-Screen

- [TUNA-Screen API](https://github.com/charlymigenes-ux/nopal/blob/main/backend/api/tunascreen.py): `backend/api/tunascreen.py`
- [TUNA device facade](https://github.com/charlymigenes-ux/nopal/blob/main/backend/services/tunascreen_service.py): `backend/services/tunascreen_service.py`
- **TUNA-Screen client**

### Other components

- **Workshop user**

## Connections

- Workshop user → Browser UI: uses
- Browser UI → FastAPI application: requests
- FastAPI application → Dashboard API: routes (evidence: `backend/main.py`)
- FastAPI application → Library and upload API: routes (evidence: `backend/main.py`)
- FastAPI application → Laser / CNC API: routes (evidence: `backend/main.py`)
- FastAPI application → Login API: routes (evidence: `backend/main.py`)
- Login API → Accounts and sessions: calls (evidence: `backend/api/auth.py`)
- FastAPI application → Plugin loading: loads (evidence: `backend/main.py`)
- Dashboard API → Workshop status: calls (evidence: `backend/api/status.py`)
- Workshop status → Klipper / Moonraker: queries (evidence: `backend/services/dashboard_service.py`)
- Workshop status → Marlin driver: queries (evidence: `backend/services/dashboard_service.py`)
- Workshop status → Bambu driver: queries (evidence: `backend/services/dashboard_service.py`)
- Workshop status → Elegoo driver: queries (evidence: `backend/services/dashboard_service.py`)
- Workshop status → FlashForge driver: queries (evidence: `backend/services/dashboard_service.py`)
- Workshop status → GRBL control: queries (evidence: `backend/services/dashboard_service.py`)
- Marlin API → Marlin driver: calls (evidence: `backend/api/marlin_printers.py`)
- Laser / CNC API → GRBL control: calls (evidence: `backend/api/laser.py`)
- FastAPI application → Access policy: enforces
- Library and upload API → Model and G-code files: manages
- Browser UI → 3D / toolpath preview: previews files
- FastAPI application → AI API: routes (evidence: `backend/main.py`)
- AI API → AI agent and tools: delegates (evidence: `backend/api/ai.py`)
- FastAPI application → TUNA-Screen API: routes (evidence: `backend/main.py`)
- TUNA-Screen client → TUNA-Screen API: requests
- TUNA-Screen API → TUNA device facade: calls (evidence: `backend/api/tunascreen.py`)
- TUNA device facade → Klipper / Moonraker: delegates (evidence: `backend/services/tunascreen_service.py`)
- TUNA device facade → Marlin driver: delegates (evidence: `backend/services/tunascreen_service.py`)
- TUNA device facade → Bambu driver: delegates (evidence: `backend/services/tunascreen_service.py`)
- TUNA device facade → Elegoo driver: delegates (evidence: `backend/services/tunascreen_service.py`)
- TUNA device facade → FlashForge driver: delegates (evidence: `backend/services/tunascreen_service.py`)
- TUNA device facade → GRBL control: delegates (evidence: `backend/services/tunascreen_service.py`)
