#Product architecture
#System context
Browser
Central frontend (Next.js 16, frontend-2)
Central backend
sa-central-api-2 (Laravel 13, Passport, MariaDB sv_central_2, Redis, Horizon)
External
Each server's OSS panel API (Bearer sv_central_…)Payment gatewaysCloud providers (DigitalOcean, Linode, Vultr, Hetzner, Lightsail…)MailTurnstileGoogle / GitHub OAuth
- The browser only talks to sa-central-api-2. It never calls an OSS panel or a provider directly. Server keys and provider tokens stay on the backend. V8 requirement R5 (common OSS client) · Security
- sa-central-api-2 holds accounts, organizations, billing, roles and a small link record per server. It calls OSS panels through one shared OSS client (built with the Servers phase, not the Foundation phase — backend update 2026-10-03) that handles auth headers, timeouts, retries, error mapping and secret-free logging. V8 requirement §2.2
- OSS panels answer with live data. The Central key signs in as a machine administrator account on that panel (
CentralSystemGuard). It can use the whole OSS API except creating, changing or deleting panel users and roles. OSS API
#What lives where (V8 rule R5)
| Central database (stored) | OSS panel (fetched live, never stored in Central) |
|---|---|
| Users, login data, 2FA, IP whitelist, sessions | Server facts, metrics, processes |
| Organizations, members, roles, permissions | Applications and everything inside them |
| Plans, subscriptions, wallet, transactions, invoices | Databases, system users, services, firewall, cron, backups… |
| Providers (encrypted tokens) | OSS's own activity log ("central" machine account) |
| A few link fields per server (which ones is still open, Q1) | Panel version, health |
| Blueprints (Central stores them, as V7 did; OSS runs them) OSS API | Add-on run results |
| Central audit log, notifications |
V8 requirement §2.1
#Request path
Browsersa-central-api-2 (auth + organization + permission + plan checks)OSS client (server key, timeout, retry)OSS panel APIresponse mapped to Central error codesBrowser
#Frontend architecture
| Layer | Choice | Status |
|---|---|---|
| Framework | Next.js 16 App Router, JavaScript only | Confirmed scaffold |
| UI | shadcn/ui primitives in components/ui/ (button, card, dialog, dropdown, input, select, sheet, table, tabs, tooltip, sonner…), Tailwind v4 | Confirmed scaffold |
| i18n | next-intl, /[locale]/… routes, messages/<locale>.json | Required by project rules. Not installed yet Missing |
| Forms | react-hook-form + zod | zod installed · react-hook-form not installed Missing |
| Tables | TanStack Table v8 | Not installed Missing |
| HTTP | axios instance in lib/api/ with interceptors | axios installed · client not written |
| State | Zustand for cross-component UI state (current organization, sidebar) | installed |
| Charts | Recharts | installed |
| Theme | next-themes | installed |
Rule for the build: server components by default, "use client" only where state, effects or browser APIs are needed. Every route group gets loading, error and not-found. The frontend is a view layer with no business logic.
#Backend architecture (from the V8 doc)
| Concern | Decision | Source |
|---|---|---|
| Framework | Laravel 13 | V8 requirement Phase 1 |
| Database | MariaDB, separate per pair (sv_central / sv_central_2), utf8mb4, strict | V8 requirement (currently still SQLite in .env) |
| Cache / sessions / queue | Redis; Horizon queues default, notifications, emails | V8 requirement |
| API auth | Laravel Passport: access 15 days, refresh 30 days, personal token 6 months | V8 requirement |
| CORS | Only the configured frontend URL; api/*, oauth/*; Authorization header | V8 requirement |
| Logs | Daily, 14 days, never tokens/passwords/Authorization | V8 requirement |
| Tests | Pest for every endpoint; OSS faked with Http::fake | V8 requirement |