CoaxysPanel/README.md

CoaxysPanel

CoaxysPanel is a frontend-only hosting control center built with Next.js App Router, React, TypeScript, Tailwind CSS, shadcn/Radix primitives, TanStack Query/Table, Recharts, Monaco Editor, xterm.js, dnd-kit, Zustand, React Hook Form, Zod, Vitest, and Playwright.

Installation

npm install

The project includes .npmrc with the default npm registry: https://registry.npmjs.org/.

Development

npm run dev

Open http://localhost:3000. The app redirects to /dashboard; auth flows are available at /login.

Build

npm run typecheck
npm run build

Testing

npm run lint
npm run test
npm run test:e2e

Backend routine checks:

cd backend
npm run lint
npm run test
npm run build

The backend also has npm run test:resilience for explicit PostgreSQL/Redis outage tests. Do not run that command on a shared or production host unless service disruption is acceptable.

Environment Variables

No secrets are required. Future backend integration can use NEXT_PUBLIC_API_BASE_URL, NEXT_PUBLIC_MOCK_LATENCY_MS, and NEXT_PUBLIC_MOCK_ERROR_RATE.

To use the real Fastify backend instead of the in-browser mock service layer, set:

NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:3020

For production behind Nginx, prefer a same-origin proxy:

NEXT_PUBLIC_API_BASE_URL=same-origin

Then proxy /api/* from the public host to the backend process. Full origins such as https://api.example.com and base paths such as https://cp.example.com/api are also supported. When this variable is unset, the frontend stays in mock-data mode. When it is set, panelService uses credentialed HTTP requests against the backend API while preserving the same { data, meta, error } response envelopes.

Mock-Data Mode

All UI reads through src/api/services/panel-service.ts, which returns typed API envelopes:

{ "data": {}, "meta": {}, "error": null }

Appearance & Theming

The UI uses a liquid-glass design system driven entirely by CSS variables. Users customize it live from Settings → Appearance (persisted to localStorage via the coaxyspanel-ui Zustand store):

• Theme: light / dark / system (class-based dark mode, no-flash inline bootstrap script). Dark mode is pitch black with strictly neutral grays — color enters only via the accent.
• Accent: azure, violet, emerald, sunset, rose, cyan — applied as data-accent on <html>, recoloring the whole panel including the logo and charts.
• Glass intensity: off / subtle / standard / heavy — data-glass controls surface translucency and backdrop blur (.glass-panel, .glass-bar, .glass-modal utilities).
• Corner radius: sharp / rounded / soft (data-radius → --radius).
• Ambient background: aurora gradients, grid, and grain (data-ambiance).
• Density: compact / comfortable.

Tokens live in src/app/globals.css; fonts (Bricolage Grotesque, Instrument Sans, JetBrains Mono) are self-hosted through next/font. All animations respect prefers-reduced-motion.

Project Structure

• src/app: Next.js App Router pages and providers.
• src/api: typed contracts, mock client, seeded mock data, and service interfaces.
• src/components: shared UI, app shell, and feature components.
• src/features: feature-specific flow code.
• src/lib: route registry, permissions, design tokens, utilities.
• src/stores: Zustand UI state.
• tests: Vitest unit/component tests and Playwright flows.

Major Features

Dashboard, universal tool launcher, websites, domains and DNS, file manager, databases, email, metrics, security, software/runtimes, advanced tools, terminal, server administration, users, roles, resellers, backups, automation, notifications, audit logs, support, settings, and complete frontend authentication flows.

Backend Integration

Replace panelService methods with HTTP implementations that preserve the contracts in src/api/contracts. Components already consume service interfaces and response envelopes rather than raw JSON.

The backend lives in backend/ and is a Fastify + TypeScript + Prisma app. The current frontend can switch between mock and backend mode through NEXT_PUBLIC_API_BASE_URL; no component imports need to change.

The backend now covers the active panel surface for auth, dashboard summaries, websites, domains, DNS, files, databases, mailboxes, metrics, security findings, backups, automations, notifications, audit logs, software runtimes, servers, users, roles, resellers, packages, settings, and support tickets. Provisioning-style actions such as file operations, backup restore, security scans, automation runs, and server actions return typed job envelopes and audit entries; they do not execute host commands.

Production deployment assets live in deploy/:

• deploy/systemd/coaxyspanel-backend.service runs the Fastify API on 127.0.0.1:3020.
• deploy/nginx/cp.asabbagh.com proxies /api/* and /health to the backend and all other traffic to the Next.js frontend on 127.0.0.1:3110.
• .env.production sets NEXT_PUBLIC_API_BASE_URL=same-origin, so browser requests stay on https://cp.asabbagh.com/api/*.