jbrueckner/GhostGrid
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1526d2514446fafba5fcb3feb0adf1c53e494789
GhostGrid/ARCHITECTURE.md

825 lines
38 KiB
Markdown
Raw Blame History

# GhostGrid
## Architecture Reference
**Status:** Living document — single source of truth for the codebase
> Use this document as the starting context for any future task on GhostGrid. It describes the whole application: purpose, stack, file layout, data model, REST API, frontend structure, integrations, background jobs, security, and deployment.
---
## 1. Executive Summary
**GhostGrid** is an internal, offline-capable **network-lab and device-inventory tool** for managing hardware lab environments. Teams use it to keep a device inventory with live status, define lab templates (devices + topology), book labs for a time window, and automatically run Ansible playbooks at booking start/end. It pulls live device status from CheckMK and can manage Caddy reverse-proxy routes and Microsoft Entra ID SSO from its own UI.
### Key Design Decisions
| Aspect | Choice | Rationale |
|--------|--------|-----------|
| Scope | Single-tenant internal tool | Small team / lab operations, not multi-tenant SaaS |
| Process model | **One Node.js process** serving API + frontend | Simple to deploy, no orchestration needed |
| Backend | Express 4 + TypeScript | Minimal, well-understood, fast to iterate |
| Frontend | React 19 + Vite 6 | Modern SPA, no router dependency (tab state) |
| Database | **SQLite** (`better-sqlite3`, WAL) | Zero-ops, single file, synchronous, perfect for air-gapped LAN |
| Styling | Tailwind CSS v4 | Utility-first, dark/light theme via class toggle |
| Auth | Local JWT + optional Azure Entra ID OAuth | Self-contained, SSO optional |
| Offline | Fonts bundled via `@fontsource` | No CDN / external runtime assets |
| Integrations | CheckMK, Ansible Semaphore, Caddy | All configured at runtime in the Settings UI (stored in DB) |
| Deployment | Proxmox LXC + systemd, two instances | Manual `git pull && build && restart` model |
**Core constraint:** runs **fully offline**. No external code, assets, or CDN resources are loaded at runtime.
---
## 2. System Architecture
### 2.1 High-Level Architecture
```
+-----------------------------------------------------------------------------+
| GHOSTGRID PLATFORM |
+-----------------------------------------------------------------------------+
| +---------------------------------------------------------------------+ |
| | PRESENTATION LAYER | |
| | +-----------------------------+ +----------------------------+ | |
| | | React 19 SPA (Vite) | | Browser localStorage | | |
| | | - Tab-based navigation | | - ghostgrid_token (JWT) | | |
| | | - Tailwind dark/light | | - ghostgrid_user | | |
| | +-----------------------------+ +----------------------------+ | |
| +---------------------------------------------------------------------+ |
| | authFetch > Bearer <JWT> |
| +---------------------------------------------------------------------+ |
| | APPLICATION LAYER (server.ts) | |
| | Single Express process — serves API + frontend | |
| | +-----------+ +-----------+ +-----------+ +-----------+ +--------+ | |
| | | Auth | | Devices | | Labs | | Bookings | | Logs | | |
| | | (JWT/MSAL)| | CRUD | | CRUD | | CRUD | | | | |
| | +-----------+ +-----------+ +-----------+ +-----------+ +--------+ | |
| | +-----------+ +-----------+ +-----------+ +-----------+ | |
| | | Users | | Links | | Settings | | Caddy | | |
| | +-----------+ +-----------+ +-----------+ +-----------+ | |
| | +---------------------------------------------------------------+ | |
| | | Background jobs (self-rescheduling setTimeout loops) | | |
| | | - CheckMK status sync (default 60s) | | |
| | | - Semaphore setup/teardown trigger (30s) | | |
| | +---------------------------------------------------------------+ | |
| +---------------------------------------------------------------------+ |
| | |
| +---------------------------------------------------------------------+ |
| | DATA LAYER (server-db.ts) | |
| | +-------------------------------------------------------------+ | |
| | | SQLite — ghostgrid.db (better-sqlite3, WAL) | | |
| | | users · devices · labs · bookings · logs · links | | |
| | | settings · caddy | | |
| | +-------------------------------------------------------------+ | |
| +---------------------------------------------------------------------+ |
+-----------------------------------------------------------------------------+
| EXTERNAL INTEGRATIONS |
| +-------------+ +------------------+ +-----------+ +----------------+ |
| | CheckMK | | Ansible Semaphore| | Caddy | | Microsoft | |
| | REST API | | REST API | | Admin API | | Entra ID (MSAL)| |
| | (status) | | (playbook tasks) | | (/load) | | (OAuth 2.0) | |
| +-------------+ +------------------+ +-----------+ +----------------+ |
+-----------------------------------------------------------------------------+
```
### 2.2 Component Breakdown
#### 2.2.1 Presentation Layer
| Component | Technology | Purpose |
|-----------|------------|---------|
| Web UI | React 19 + TypeScript | Dashboard, booking calendar, inventory, topology, settings |
| Build/dev server | Vite 6 | Bundles the SPA; mounted as Express middleware in dev |
| Session store | Browser `localStorage` | Persists JWT + user between reloads |
#### 2.2.2 Application Layer (`server.ts` — single process)
| Route group | Responsibility |
|---------|----------------|
| Auth | Local register/login (JWT), Azure Entra ID OAuth, `/me`, public `/config` |
| Devices | Inventory CRUD; delete also scrubs the device from labs |
| Labs | Lab-template CRUD; `deviceIds`/`topology` stored as JSON |
| Bookings | Reservation CRUD; cancellation can trigger Semaphore teardown |
| Logs | Audit/maintenance journal (read + manual create) |
| Users | Team list, edit, delete (self/last-user guarded) |
| Links | Shared quick-links dashboard CRUD |
| Settings | Integration config (Azure, CheckMK, Semaphore, Caddy); secrets masked |
| CheckMK | Manual sync trigger |
| Semaphore | Template-list proxy, manual setup/teardown trigger |
| Caddy | Status, route CRUD, Caddyfile push |
| Background jobs | CheckMK sync loop + Semaphore trigger loop |
| Static serving | Vite middleware (dev) / static `dist/` + SPA fallback (prod) |
#### 2.2.3 Data Layer (`server-db.ts`)
| Component | Technology | Purpose |
|-----------|------------|---------|
| Database | SQLite via `better-sqlite3` | Single file `ghostgrid.db`, WAL journal mode, synchronous queries |
| Schema | Idempotent `CREATE TABLE IF NOT EXISTS` | 8 tables defined in full and created on boot (fresh-install model, no migrations) |
| Settings store | key/value `settings` table | Runtime config for all integrations, seeded with `INSERT OR IGNORE` |
---
## 3. Technology Stack
### 3.1 Backend Stack
```
Node.js 20 LTS (TypeScript ~5.8, ES modules)
+-- Web Framework
| +-- express 4.21 (HTTP server, routing, JSON middleware)
| +-- vite 6 (createServer) (dev middleware mode, SPA)
+-- Auth & Security
| +-- jsonwebtoken 9 (JWT sign/verify, 24h expiry)
| +-- bcryptjs 2.4 (password hashing, cost 10)
| +-- @azure/msal-node 5 (Entra ID OAuth 2.0 auth-code flow)
+-- Data Access
| +-- better-sqlite3 12 (synchronous SQLite driver, WAL)
+-- Utilities
| +-- dotenv 17 (.env loading)
| +-- (global fetch) (CheckMK / Semaphore / Caddy HTTP calls)
+-- Build / Run
+-- tsx 4 (dev: run server.ts directly)
+-- esbuild 0.25 (bundle server > dist/server.cjs)
```
### 3.2 Frontend Stack
```
React 19 + TypeScript
+-- State Management
| +-- React hooks only (useState/useEffect in App.tsx — no Redux/Zustand)
| +-- localStorage (token + user persistence via src/lib/auth.ts)
+-- UI / Styling
| +-- tailwindcss 4 (@tailwindcss/vite plugin)
| +-- lucide-react 0.546 (icon set)
+-- Fonts (self-hosted, offline)
| +-- @fontsource/inter
| +-- @fontsource/jetbrains-mono
+-- Networking
| +-- fetch + authFetch() (thin wrapper injecting Authorization header)
+-- Build Tools
+-- vite 6 + @vitejs/plugin-react
```
### 3.3 Data Layer
```
SQLite (single file: ghostgrid.db, WAL mode)
+-- users (local + Azure-provisioned accounts)
+-- devices (inventory + CheckMK-synced status)
+-- labs (templates: deviceIds[] + topology[] as JSON)
+-- bookings (reservations + Ansible trigger flags/jobs)
+-- logs (audit/maintenance journal)
+-- links (shared quick-links dashboard)
+-- settings (key/value runtime config for integrations)
+-- caddy (custom reverse-proxy routes)
```
### 3.4 Infrastructure
```
Deployment
+-- Proxmox LXC (Debian 12, unprivileged)
+-- systemd services (ghostgrid + ghostgrid-dev)
+-- Two parallel instances (main:3000, dev:3001), separate DBs
+-- deploy/proxmox-ghostgrid.sh (one-shot installer)
+-- deploy/deploy.sh <branch> (git pull + build + restart)
Networking (optional, managed in-app)
+-- Caddy reverse proxy (local_certs, tls internal)
+-- Caddyfile pushed to Caddy Admin API /load
```
---
## 4. Database Schema Design
SQLite file `ghostgrid.db` in `process.cwd()`, opened with `journal_mode = WAL`. Every table is defined in full and created idempotently on boot (`CREATE TABLE IF NOT EXISTS`) — the app assumes a fresh install, so there is no migration layer.
### 4.1 Schema (as created in `server-db.ts`)
```sql
CREATE TABLE IF NOT EXISTS users (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
role TEXT NOT NULL DEFAULT 'User',
email TEXT NOT NULL UNIQUE,
password_hash TEXT NOT NULL -- bcrypt; '' for Azure-provisioned users
);
CREATE TABLE IF NOT EXISTS devices (
id TEXT PRIMARY KEY,
hostname TEXT NOT NULL,
ip TEXT NOT NULL,
location TEXT NOT NULL,
notes TEXT,
type TEXT NOT NULL, -- Switch | Firewall | Access-Point | Controller | custom
status TEXT NOT NULL, -- online | offline | unknown
emergencySheet TEXT NOT NULL, -- markdown
lastCheckedAt TEXT,
checkMkUrl TEXT NOT NULL DEFAULT '',
cmkHostname TEXT NOT NULL DEFAULT ''
);
CREATE TABLE IF NOT EXISTS labs (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
description TEXT NOT NULL,
contactPerson TEXT NOT NULL,
location TEXT NOT NULL,
deviceIds TEXT NOT NULL, -- JSON string: string[]
topology TEXT NOT NULL, -- JSON string: TopologyLink[]
semaphoreSetupTemplateId TEXT NOT NULL DEFAULT '',
semaphoreTeardownTemplateId TEXT NOT NULL DEFAULT ''
);
CREATE TABLE IF NOT EXISTS bookings (
id TEXT PRIMARY KEY,
labId TEXT NOT NULL,
userId TEXT NOT NULL,
startDateTime TEXT NOT NULL,
endDateTime TEXT NOT NULL,
notes TEXT,
status TEXT NOT NULL, -- active | upcoming | completed | cancelled
notified INTEGER NOT NULL DEFAULT 0,
emailSent INTEGER NOT NULL DEFAULT 0,
ansibleSetupTriggered INTEGER NOT NULL DEFAULT 0,
ansibleTeardownTriggered INTEGER NOT NULL DEFAULT 0,
ansibleSetupJobId TEXT NOT NULL DEFAULT '',
ansibleTeardownJobId TEXT NOT NULL DEFAULT ''
);
CREATE TABLE IF NOT EXISTS logs (
id TEXT PRIMARY KEY,
timestamp TEXT NOT NULL,
type TEXT NOT NULL, -- maintenance | booking | status | system
message TEXT NOT NULL,
deviceId TEXT,
userId TEXT
);
CREATE TABLE IF NOT EXISTS links (
id TEXT PRIMARY KEY,
title TEXT NOT NULL,
url TEXT NOT NULL,
description TEXT NOT NULL DEFAULT '',
category TEXT NOT NULL DEFAULT '',
color TEXT NOT NULL DEFAULT 'emerald',
createdBy TEXT,
createdAt TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS settings (
key TEXT PRIMARY KEY,
value TEXT NOT NULL,
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE TABLE IF NOT EXISTS caddy (
id INTEGER PRIMARY KEY AUTOINCREMENT,
hostname TEXT NOT NULL,
upstream TEXT NOT NULL,
tls INTEGER NOT NULL DEFAULT 1,
compress INTEGER NOT NULL DEFAULT 1,
created_at TEXT DEFAULT (datetime('now'))
);
```
### 4.2 Data-Model Notes
| Topic | Detail |
|-------|--------|
| IDs | App-generated strings: `` `${prefix}-${Date.now()}-${rand}` `` (`dev-…`, `lab-…`, `book-…`, `log-…`, `u-…`, `link-…`); `caddy` uses an autoincrement integer |
| JSON columns | `labs.deviceIds` and `labs.topology` are JSON strings, parsed in the API layer |
| Booleans | Booking flags (`notified`, `emailSent`, `ansible*Triggered`) are `INTEGER` 0/1, mapped to JS booleans on read |
| Cascade | No FK cascades; referential cleanup is done in code (e.g. deleting a device scrubs it from every lab's `deviceIds`/`topology`) |
| Schema changes | Fresh-install model — edit the `CREATE TABLE` block in `server-db.ts` directly; there is no migration helper |
### 4.3 Settings (key/value config)
Seeded with `INSERT OR IGNORE` (defaults below). Secret keys are never returned raw — `maskSettings()` replaces them with the `__SET__` sentinel.
| Group | Keys (default) |
|-------|----------------|
| Azure | `azure_enabled`(false), `azure_client_id`, `azure_tenant_id`, `azure_client_secret`🔒, `azure_redirect_uri`, `azure_allowed_group` |
| CheckMK | `checkmk_enabled`(false), `checkmk_api_url`, `checkmk_api_user`(automation), `checkmk_api_secret`🔒, `checkmk_sync_interval_ms`(60000) |
| Semaphore | `semaphore_enabled`(false), `semaphore_api_url`, `semaphore_api_token`🔒, `semaphore_project_id` |
| Caddy | `caddy_enabled`(false), `caddy_admin_url`(http://localhost:2019) |
🔒 = in `SECRET_KEYS`, masked on read, only updated when a non-`__SET__` value is sent.
---
## 5. API Design
All `/api/*` routes return JSON. Every route except the public auth/config endpoints requires `requireAuth` (JWT bearer).
### 5.1 REST API Structure
```
/api
+-- /auth
| +-- POST /register # Create local account > { token, user } [public]
| +-- POST /login # Authenticate > { token, user } [public]
| +-- GET /me # Current user from token [auth]
| +-- GET /config # { azureEnabled, effectiveRedirectUri, [public]
| | # checkmkEnabled, checkmkBaseUrl }
| +-- GET /azure # Start Azure OAuth (redirect to Microsoft) [public]
| +-- GET /azure/callback # OAuth callback > redirect /?token=… [public]
|
+-- /settings
| +-- GET / # All settings (secrets masked as __SET__) [auth]
| +-- PUT / # Update allow-listed keys; re-push Caddy [auth]
|
+-- /users
| +-- GET / # List users [auth]
| +-- PUT /{id} # Update name/email (dupe-email guarded) [auth]
| +-- DELETE /{id} # Delete (not self, not last user) [auth]
|
+-- /devices
| +-- GET / # List devices [auth]
| +-- POST / # Create device (+ maintenance log) [auth]
| +-- PUT /{id} # Update device (+ maintenance log) [auth]
| +-- DELETE /{id} # Delete + scrub from all labs [auth]
|
+-- /labs
| +-- GET / # List labs (parses deviceIds/topology JSON) [auth]
| +-- POST / # Create lab [auth]
| +-- PUT /{id} # Update lab [auth]
| +-- DELETE /{id} # Delete + cancel upcoming bookings [auth]
|
+-- /bookings
| +-- GET / # List bookings (int flags > booleans) [auth]
| +-- POST / # Create booking (+ log, alertGenerated) [auth]
| +-- PUT /{id} # Update status; cancel>teardown trigger [auth]
| +-- DELETE /{id} # Delete booking [auth]
|
+-- /logs
| +-- GET / # All logs, newest first [auth]
| +-- POST / # Manual log entry [auth]
|
+-- /links
| +-- GET / # Quick links (ordered category, title) [auth]
| +-- POST / # Create link [auth]
| +-- PUT /{id} # Update link [auth]
| +-- DELETE /{id} # Delete link [auth]
|
+-- /checkmk
| +-- POST /sync # Trigger CheckMK status sync now [auth]
|
+-- /semaphore
| +-- GET /templates # Proxy Semaphore task-template list [auth]
| +-- POST /trigger/{bookingId} # Manual setup|teardown for a booking [auth]
|
+-- /caddy
+-- GET /status # Caddy admin API reachable? [auth]
+-- GET /routes # { system, custom } routes [auth]
+-- POST /routes # Add custom route + push config [auth]
+-- PUT /routes/{id} # Update custom route + push config [auth]
+-- DELETE /routes/{id} # Remove custom route + push config [auth]
```
### 5.2 Authentication & Authorization
```
Auth model
+-- Token: JWT (HS256, secret = JWT_SECRET), payload { userId, email }, expiry 24h
+-- Transport: Authorization: Bearer <jwt> (no cookies > no CSRF surface)
+-- Storage: browser localStorage (ghostgrid_token, ghostgrid_user)
+-- Middleware
| +-- requireAuth — verifies JWT, sets req.user; applied to all data routes
| +-- requireAdmin — checks users.role === 'admin' ⚠ DEFINED BUT NOT WIRED
+-- Roles: role column defaults to 'User'; no route currently enforces admin
```
**Local flow:** `register` (bcrypt hash, role `User`) / `login` (bcrypt compare) > issue JWT > client stores token + user.
**Azure Entra ID (OAuth 2.0 auth-code flow):**
```
1. GET /api/auth/config > frontend learns azureEnabled, shows SSO button
2. GET /api/auth/azure > MSAL getAuthCodeUrl > 302 to Microsoft
3. GET /api/auth/azure/callback> acquireTokenByCode
> optional azure_allowed_group membership check
> upsert user (auto-provision, empty password)
> 302 /?token=<jwt>
4. App.tsx reads ?token= / ?auth_error=, verifies via /api/auth/me, persists
```
---
## 6. Integrations & Background Jobs
All three integrations are configured at runtime via the Settings UI (stored in the `settings` table). The background loops re-read settings each cycle, so CheckMK interval changes take effect without a restart.
### 6.1 CheckMK — Device Status Sync
```
Loop: scheduleSync() > syncCheckMkStatuses() > setTimeout(checkmk_sync_interval_ms)
(default 60s; skipped entirely if checkmk_enabled !== 'true')
Auth header: Authorization: Bearer <user> <secret>
Step 1 GET /domain-types/host_config/collections/all
> build IP > hostname map (checks attributes + effective_attributes)
Step 2 for each device:
- no CheckMK host for its IP > status 'unknown'
- GET /objects/host/{name}?columns=state…
state 0 > online
state 1 | 2 > offline
else > unknown
- update devices.status, lastCheckedAt, cmkHostname
- on change: write a 'status' log
Summary log per cycle: "<online> online, <offline> offline, <unknown> unknown"
HTTP hints: 401/403/404 mapped to actionable messages (checkmkHttpHint)
```
### 6.2 Ansible Semaphore — Playbook Automation
```
Loop: scheduleSemaphoreCheck() > checkAndTriggerAnsibleTasks() > setTimeout(30s)
(skipped if semaphore_enabled !== 'true')
Setup bookings WHERE startDateTime <= now AND ansibleSetupTriggered=0
AND status != 'cancelled' > trigger lab.semaphoreSetupTemplateId
Teardown bookings WHERE endDateTime <= now AND ansibleTeardownTriggered=0
AND status != 'cancelled' > trigger lab.semaphoreTeardownTemplateId
(also triggered immediately when a started booking is cancelled)
triggerSemaphoreTask(templateId, extraVars):
POST {apiUrl}/api/project/{projectId}/tasks
body { template_id, environment: JSON.stringify(extraVars) }
extraVars = { booking_id, lab_name, user_id, start_time, end_time }
> store returned job id on booking; log success/failure
(a booking with no template id is marked triggered > not retried)
Manual: POST /api/semaphore/trigger/{bookingId} body { type: 'setup'|'teardown' }
GET /api/semaphore/templates (proxy for UI dropdowns)
```
### 6.3 Caddy — Reverse Proxy
```
buildCaddyfile():
{ local_certs } # global block
per custom route { [encode] [tls internal] reverse_proxy <upstream> }
importCaddyfileRoutes(): reads /etc/caddy/Caddyfile on first Caddy enable
parses hostname/upstream blocks → seeds caddy table as custom routes
(no-op if caddy table already has entries or file not found)
pushCaddyConfig(): POST <caddy_admin_url>/load (Content-Type: text/caddyfile)
called on startup, after settings save, after route add/delete
(failures logged as warnings, non-fatal; skipped if caddy_enabled !== 'true')
```
---
### 6.4 First-start Initialization
Runs in `startServer()` before any routes are registered, every startup — both operations
are idempotent and only fire once on a blank database.
```
Default admin user:
if users table is empty:
INSERT user (name='Admin', role='Admin', email='admin@ghostgrid.local', password=bcrypt('admin'))
→ log "[Init] Default admin user created"
Default settings:
INSERT OR IGNORE all DEFAULT_SETTINGS keys from server-db.ts
→ existing values in the settings table are never overwritten
```
---
## 7. Frontend Architecture
### 7.1 Application Structure
```
src/
+-- main.tsx # React entry: imports fonts + index.css, renders <App/>
+-- App.tsx # Stateful root: auth gate, data loading, tab routing, all handlers
+-- index.css # Tailwind + theme tokens
+-- types.ts # Shared interfaces (Device, LabTemplate, Booking, …) — see §8
+-- vite-env.d.ts
+-- lib/
| +-- auth.ts # localStorage token/user, authFetch() wrapper, session helpers
+-- components/
+-- Header.tsx # Top bar; exports GhostGridLogo; notifications; theme/logout
+-- Dashboard.tsx # Active/upcoming bookings + quick-links widget
+-- BookingCalendar.tsx # Day-offset grid; create/cancel; conflict + online checks
+-- BookingDetailsModal.tsx # Booking detail; manual Semaphore trigger; cancel/delete
+-- DeviceInventory.tsx # List/detail; CRUD; markdown emergency sheet; CheckMK link
+-- LabTemplates.tsx # Lab CRUD + topology editor; embeds TopologyPanel
+-- TopologyPanel.tsx # Pure SVG (800x400) node/link renderer
+-- Logbook.tsx # Sorted/filtered log list + manual entry
+-- LinkDashboard.tsx # Quick-link CRUD; 6 accent colors; category grouping
+-- UserDirectory.tsx # Team list; avatar colors; edit/delete modal
+-- LoginPage.tsx # Local login + Azure SSO button (if enabled)
+-- RegisterPage.tsx # Self-registration form
+-- Settings.tsx # Integration config cards (Azure, CheckMK, Semaphore, Caddy)
```
### 7.2 State & Data Flow
`App.tsx` is the single stateful root (no router, no global store):
```
+-- Auth state: currentUser (from localStorage), authView (login|register), authChecked
+-- App data: users, devices, labs, bookings, logs, links (loaded in one Promise.all)
+-- UI state: activeTab, navCollapsed*, theme* (dark|light), notifications,
| selectedBookingForDetails, inventoryHighlightDevice, checkmk{Enabled,BaseUrl}
+-- Effects:
| +-- Startup token verify + OAuth ?token=/?auth_error= handling
| +-- Load data on login
| +-- Poll GET /api/devices every 30s (surface CheckMK-driven status changes)
| +-- Booking reminder check every 60s (fires once per upcoming booking ≤30min away)
+-- Handlers: handleAdd/Update/Delete* for bookings, devices, labs, links, users +
handleAddLogManually — call API via authFetch, update local state,
most then refetch /api/logs
(* persisted to localStorage)
```
**Navigation** is a plain `activeTab` switch. Groups: Dashboard / Lab Management (Booking, Inventory, Topology) / Resources (Quick Links, Team) / Audit (Logbook) / System (Settings).
### 7.3 Key UI Components
```
Dashboard
+-- Active / upcoming booking cards
+-- Quick-links widget
+-- Navigation shortcuts (to calendar, devices, labs, links)
Booking Calendar
+-- Day-offset grid
+-- Create booking with conflict detection + device-online validation
+-- (devices in 'unknown' status are not bookable when CheckMK enabled)
Device Inventory
+-- Searchable list + detail panel
+-- CRUD; class presets (Switch/Firewall/Access-Point/Controller) + free-form
+-- Markdown emergency sheet; optional CheckMK deep-link
Lab Templates + Topology
+-- Lab CRUD; Semaphore setup/teardown template selection
+-- Topology link editor (fromDevice > toDevice, link type)
+-- TopologyPanel: SVG layout by node count (1 / 2 / 3 / circular)
Settings
+-- Microsoft Entra ID (OAuth SSO, redirect-URI helper, allowed group)
+-- CheckMK (API URL/user/secret, sync interval, "Run sync now")
+-- Ansible Semaphore (API URL/token/project, "Test connection")
+-- Caddy (admin URL, custom route management;
auto-seeded from /etc/caddy/Caddyfile on first enable)
+-- Secret inputs use the __SET__ sentinel (blank = keep existing)
```
---
## 8. Shared Types (`src/types.ts`)
The single contract between frontend and backend — imported by **both** `server.ts` and the React components.
| Type | Notes |
|------|-------|
| `DeviceType` | `'Switch' \| 'Access-Point' \| 'Firewall' \| 'Controller' \| (string & {})` — presets + free-form |
| `Device` | `status: 'online' \| 'offline' \| 'unknown'`; `emergencySheet` markdown; optional `cmkHostname`, `lastCheckedAt` |
| `TopologyLink` | `{ fromDevice, toDevice, type }` (e.g. `LACP-Trunk`, `Uplink`, `OOB-Management`) |
| `LabTemplate` | `deviceIds: string[]`, `topology: TopologyLink[]`, optional Semaphore template IDs |
| `Booking` | `status: 'active' \| 'upcoming' \| 'completed' \| 'cancelled'`; ansible trigger flags + job IDs |
| `LogEntry` | `type: 'maintenance' \| 'booking' \| 'status' \| 'system'` |
| `User` | `{ id, name, role, email }` (never password on the client) |
| `QuickLink` | `{ id, title, url, description, category, color, createdBy?, createdAt }` |
---
## 9. Deployment Architecture
### 9.1 Process & Build Model
```
Dev : npm run dev > tsx server.ts
Express + Vite middleware (HMR) on :3000
Build : npm run build
vite build > dist/ (frontend)
esbuild server.ts --bundle --platform=node --format=cjs
--packages=external > dist/server.cjs
Prod : NODE_ENV=production node dist/server.cjs
Express serves static dist/ + SPA fallback (GET * > dist/index.html)
```
### 9.2 Proxmox LXC + systemd (two instances)
```
+----------------------- Proxmox LXC (Debian 12) -----------------------+
| |
| Production Staging |
| +-------------------------+ +-----------------------------+ |
| | branch : main | | branch : dev | |
| | dir : /opt/ghostgrid| | dir : /opt/ghostgrid-dev | |
| | port : 3000 | | port : 3001 | |
| | service : ghostgrid | | service : ghostgrid-dev | |
| | db : ghostgrid.db | | db : ghostgrid.db (own) | |
| | .env : own JWT_SECRET| | .env : own JWT_SECRET | |
| +-------------------------+ +-----------------------------+ |
| |
| Both exposed directly on the LAN (no reverse proxy / TLS by default; |
| the in-app Caddy feature can add this). |
+-----------------------------------------------------------------------+
Install : deploy/proxmox-ghostgrid.sh (creates LXC, Node 20, clones both
branches, builds, configures services)
Update : deploy/deploy.sh <branch> (git pull + npm run build + systemctl restart;
defaults to main)
Backup : ghostgrid.db + ghostgrid.db-wal + ghostgrid.db-shm
```
### 9.3 Environment Variables
| Var | Default | Purpose |
|-----|---------|---------|
| `JWT_SECRET` | insecure fallback | Sign/verify JWTs — **must be set in production** |
| `APP_URL` | `http://localhost:<PORT>` | Base URL for deriving the Azure redirect URI |
| `PORT` | `3000` | HTTP listen port |
| `NODE_ENV` | — | `production` switches to static `dist/` serving |
| `CHECKMK_API_URL` / `CHECKMK_API_USER` / `CHECKMK_API_SECRET` | — | Fallbacks if not set in the Settings UI |
---
## 10. Security Architecture
```
+-------------------------------------------------------------+
| SECURITY OVERVIEW |
+-------------------------------------------------------------+
| Authentication |
| +-- Local users: bcrypt password hashing (cost 10) |
| +-- JWT (HS256), 24h expiry, no refresh tokens |
| +-- Token in Authorization header (not cookies) |
| +-- Optional Azure Entra ID SSO (MSAL), group restriction |
+-------------------------------------------------------------+
| Authorization |
| +-- requireAuth on all data routes |
| +-- role column ('User'/'admin') exists |
| +-- ⚠ requireAdmin defined but NOT applied — any |
| authenticated user can read/write settings + users |
+-------------------------------------------------------------+
| Secret Handling |
| +-- Integration secrets stored in settings table |
| +-- Masked as __SET__ on read (SECRET_KEYS) |
| +-- Only overwritten when a non-sentinel value is sent |
+-------------------------------------------------------------+
| Notable gaps / accepted risks |
| +-- JWT_SECRET has an insecure fallback if unset |
| +-- POST /api/bookings trusts client-supplied userId |
| (does not force req.user.userId) |
| +-- No rate limiting on auth endpoints |
| +-- Secrets at rest are plaintext in SQLite (file perms |
| are the protection boundary) |
+-------------------------------------------------------------+
```
---
## 11. Project Structure
```
GhostGrid/
+-- server.ts # Express app: all routes, auth, integrations, background jobs
+-- server-db.ts # SQLite connection, full schema, settings/Caddy helpers
+-- index.html # Vite HTML entry (#root > src/main.tsx)
+-- vite.config.ts # Vite + React + Tailwind; '@' alias > repo root
+-- tsconfig.json # noEmit, react-jsx, bundler resolution
+-- package.json # scripts + deps (package name "react-example" is vestigial)
+-- .env.example # JWT_SECRET, APP_URL
+-- metadata.json # app name/description metadata
+-- README.md # user-facing overview
+-- DEPLOY.md # Proxmox LXC / systemd deployment guide
+-- ARCHITECTURE.md # ← this file
+-- deploy/
| +-- deploy.sh # git pull + build + systemctl restart (arg: branch)
| +-- ghostgrid.service # systemd unit — production (main, :3000)
| +-- ghostgrid-dev.service # systemd unit — staging (dev, :3001)
| +-- proxmox-ghostgrid.sh # one-shot LXC installer (Proxmox VE helper-script style)
+-- src/
+-- main.tsx # React entry
+-- App.tsx # root component (state, routing, handlers)
+-- index.css # Tailwind + theme
+-- types.ts # shared TS interfaces
+-- vite-env.d.ts
+-- lib/auth.ts # token storage + authFetch
+-- components/ # 14 components (see §7.1)
# Runtime artifacts (gitignored):
# ghostgrid.db, ghostgrid.db-wal, ghostgrid.db-shm, dist/, node_modules/
```
---
## 12. Key Technical Decisions Summary
| Decision | Choice | Rationale |
|----------|--------|-----------|
| **Process model** | Single Express process serves API + SPA | No orchestration; trivial LXC deployment |
| **Database** | SQLite (`better-sqlite3`, synchronous, WAL) | Zero-ops, single file, ideal for LAN/air-gap |
| **Auth** | JWT in `localStorage` + optional Azure MSAL | Self-contained; SSO optional, header-based (no CSRF) |
| **Frontend state** | React hooks only (no Redux/Zustand/router) | App is small; one stateful root is enough |
| **Runtime config** | Integration settings in DB, edited in Settings UI | No redeploy to change CheckMK/Semaphore/Caddy/Azure |
| **Background jobs** | Self-rescheduling `setTimeout` loops | Picks up settings changes each cycle; no cron/queue dep |
| **Styling** | Tailwind v4 + class-based dark/light | Utility-first, theme toggled on `<html>` |
| **Offline** | Fonts bundled via `@fontsource` | No CDN / external runtime fetches |
| **Build** | Vite (frontend) + esbuild (server bundle) | Fast, single `dist/server.cjs` output |
---
## 13. Operational Notes & Risk Mitigation
| Risk / Concern | Mitigation / Status |
|----------------|---------------------|
| Missing `JWT_SECRET` in prod | Documented in `.env.example`/DEPLOY.md; **set per instance** (installer generates a random one) |
| No admin RBAC enforced | `requireAdmin` exists — wire it onto `/api/settings` and `/api/users` if stricter control is needed |
| Client-supplied `userId` on booking create | Force `req.user.userId` server-side if spoofing is a concern |
| CheckMK/Semaphore outage | Integration loops catch errors, log them, and retry next cycle; non-fatal |
| Caddy admin API unreachable | `pushCaddyConfig()` failures are logged as warnings; routes apply when Caddy starts |
| Data loss | Back up `ghostgrid.db` + `-wal`/`-shm`; each instance has its own DB |
| Schema evolution | Edit the `CREATE TABLE` block in `server-db.ts` (fresh-install model, no migrations); new settings need seed + allow-list (+ `SECRET_KEYS` if secret) |
---
## 14. Dependencies and Libraries
### 14.1 Backend (`dependencies`)
```
@azure/msal-node ^5.2.2 # Entra ID OAuth
@fontsource/inter ^5.2.8 # self-hosted font (used by frontend build)
@fontsource/jetbrains-mono ^5.2.8
@tailwindcss/vite ^4.1.14 # Tailwind v4 Vite plugin
@vitejs/plugin-react ^5.0.4
bcryptjs ^2.4.3 # password hashing
better-sqlite3 ^12.10.0 # SQLite driver
dotenv ^17.2.3 # .env loading
express ^4.21.2 # HTTP server
jsonwebtoken ^9.0.2 # JWT
lucide-react ^0.546.0 # icons
react / react-dom ^19.0.1
vite ^6.2.3
```
### 14.2 Dev / Build (`devDependencies`)
```
@types/bcryptjs, @types/better-sqlite3, @types/express,
@types/jsonwebtoken, @types/node # type definitions
esbuild ^0.25.0 # bundle server.ts > dist/server.cjs
tailwindcss ^4.1.14
tsx ^4.21.0 # run TS directly in dev
typescript ~5.8.2
```
### 14.3 npm Scripts
| Script | Command | Purpose |
|--------|---------|---------|
| `dev` | `tsx server.ts` | Dev server (Express + Vite middleware) on :3000 |
| `build` | `vite build && esbuild server.ts … --outfile=dist/server.cjs` | Build frontend + bundle server |
| `start` | `node dist/server.cjs` | Run production build (`NODE_ENV=production`) |
| `clean` | `rm -rf dist server.js` | Remove build artifacts |
| `lint` | `tsc --noEmit` | Type check |
---
## 15. Quick Mental Model (for future prompts)
```
Browser (React SPA, localStorage JWT)
│ authFetch > Authorization: Bearer <jwt>
▼
Express (server.ts) ──► better-sqlite3 (ghostgrid.db, WAL)
├─ /api/auth/* (JWT local + Azure MSAL)
├─ /api/{devices,labs,bookings,logs,links,users,settings}
├─ /api/checkmk/* ── background: ~60s status sync
├─ /api/semaphore/* ── background: 30s setup/teardown trigger
└─ /api/caddy/* ── pushes Caddyfile to Caddy admin API
│
└─ serves frontend: Vite middleware (dev) / static dist/ (prod)
```
**Invariants to remember when editing:**
- Frontend and backend share `src/types.ts` — change both sides together.
- `labs.deviceIds` / `labs.topology` are JSON strings in SQLite, parsed in the API.
- Booking boolean flags are 0/1 integers in SQLite, mapped on read.
- A new settings key must be: **seeded** in `server-db.ts`, **allow-listed** in `PUT /api/settings`, and (if secret) added to `SECRET_KEYS`.
- Schema changes go straight into the `CREATE TABLE` block in `server-db.ts` — fresh-install model, no migration helper.
- All user-facing strings are in **English**.
---
*Generated from the GhostGrid codebase. Keep this document in sync when the data model, API surface, or integrations change.*
Reference in New Issue View Git Blame Copy Permalink