Beszel

# MISSION: Scaffold "Beszel" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Beszel**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Beszel
- **What It Does**: Beszel is an open-source, lightweight server monitoring tool that tracks CPU, memory, disk, network, Docker, and ZFS metrics with history and alerts through a hub-and-agent architecture.
- **Domain & Category**: Lightweight Server & Container Monitoring
- **Production Scale**: Solo Developer
- **Development Mode**: CLASSIC
- **Architectural Rationale**: Building the hub on PocketBase gives Beszel a REST API, auth, realtime updates, and SQLite storage from one embedded framework, while a separate Go agent binary keeps the footprint on monitored systems minimal, matching its stated goal of being lighter than existing monitoring solutions.
- **Live Website Reference**: https://beszel.dev
- **Source Repository**: https://github.com/henrygd/beszel
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Go, PocketBase, SQLite, React, TypeScript, Vite, Tailwind CSS, Radix UI, Recharts, Docker, Helm
- **Primary Language(s)**: Go, TypeScript
- **License of the reference repo**: MIT
- **Frontend**: React — Renders the hub dashboard SPA in internal/site, embedded into the hub Go binary at build time.; Vite — Builds the site bundle; the Makefile touches internal/site/dist/index.html so hub builds succeed without it.; Tailwind CSS — Utility CSS for the dashboard, using the v4 Vite plugin.; Radix UI — Headless components (dialog, dropdown, tabs, tooltip, switch) used across the dashboard.; Recharts — Renders CPU, memory, disk, and network history charts on system pages.
- **Backend & APIs**: Go — Implements both the hub server and the per-system monitoring agent.; PocketBase — Embedded backend framework giving the hub its REST API, auth, realtime subscriptions, and admin UI.; Cobra — Parses CLI commands and flags for the hub and agent binaries.
- **Data & persistence**: SQLite — PocketBase-managed embedded database storing systems, metric history, users, and alerts.
- **Infrastructure & deploy**: Docker — Ships multi-arch hub and agent images, including alpine, Intel, and Nvidia GPU variants.; Helm — Official Helm chart is built and version-bumped by CI on release.; GoReleaser — Cross-compiles and packages hub/agent release binaries for multiple OS/arch targets.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/henrygd/beszel @ 18f7a4b)
1. **Hub and agent are separate Go binaries in one repository**: internal/cmd/hub and internal/cmd/agent (referenced from the Makefile build-hub/build-agent targets) build independently: the hub is the dashboard/collector, and the agent runs on each monitored system, communicating metrics back to the hub.
2. **PocketBase is the entire backend, not just a database wrapper**: go.mod depends directly on github.com/pocketbase/pocketbase, which supplies the hub REST API, authentication (including OAuth2/OIDC per the README), realtime record subscriptions, and the embedded SQLite storage, avoiding a hand-built API layer.
3. **The dashboard is a React SPA embedded into the hub binary**: internal/site/package.json defines a Vite/React build; the Makefile build-web-ui target compiles it before build-hub, and build-hub-dev stubs internal/site/dist/index.html so the Go binary still compiles without a prior frontend build.
4. **SQLite runs without cgo via a pure-Go driver**: go.mod pulls in modernc.org/sqlite as an indirect dependency of PocketBase, letting the hub ship as a single static binary (per the -ldflags "-w -s" Makefile build flags) without a C toolchain at runtime.
5. **Agent-hub link uses a lightweight websocket client with optional SSH setup**: go.mod includes github.com/lxzan/gws for websocket connections and github.com/gliderlabs/ssh; the agent/ directory has dedicated connection_manager.go and client.go files handling this link, matching the READMEs description of the agent reporting metrics to the hub.
6. **Notifications are delegated to a multi-provider library, not custom integrations**: go.mod depends on github.com/nicholas-fedor/shoutrrr, which the alerts system (internal/alerts) uses to send alerts through many third-party notification services from one abstraction.
7. **GPU and hardware-sensor support is compiled conditionally per platform**: The agent/ directory has OS- and vendor-specific files (gpu_nvml_linux.go, gpu_amd_linux.go, gpu_intel_sysfs_linux.go, sensors_windows.go, fans_linux.go), and the Makefile HOST_GLIBC/AGENT_GO_TAGS logic enables NVML GPU support only on compatible glibc Linux hosts.
8. **Release automation covers binaries, Docker images, and a Helm chart from one pipeline**: The .github/workflows directory has release.yml, docker-images.yml, helm-charts.yml, and update-helm-charts.yml, plus a .goreleaser.yml, so a single tagged release produces GitHub release binaries, container images, and an updated chart.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Vite 6 with TanStack Router for fully type-safe routing. Manage server state and caching via TanStack Query v5 with optimistic UI updates.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (SQLite): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.