# 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

```bash
npm install
```

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

## Development

```bash
npm run dev
```

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

## Build

```bash
npm run typecheck
npm run build
```

## Testing

```bash
npm run lint
npm run test
npm run test:e2e
```

Backend routine checks:

```bash
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:

```bash
NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:3020
```

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

```bash
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:

```json
{ "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/*`.