Import documentation: README.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.

AGENTS.md

@@ -0,0 +1,32 @@
+# Project Architecture & Exploration
+
+This document summarizes the findings from the autonomous agents deployed to analyze the CoaxysPanel frontend repository.
+
+## 1. Features & Routing Structure
+*Explored by the Features Researcher*
+
+- **Routing Model**: Uses Next.js App Router. The application is divided into `(auth)` (for login, passwords, 2FA flows) and `(panel)` (for the authenticated control panel). The panel relies heavily on a centralized dynamic catch-all route `[...slug]` to manage over 100 configured paths without duplicating page boilerplate.
+- **Route Registry**: `src/lib/routes.ts` defines all available panel modules (e.g., Databases, Websites, Files, Security).
+- **Core Views**: Handled by the `FeaturePage` component which dynamically loads the relevant feature (like the Dashboard, File Manager, DNS Editor, or Terminal) based on the current path and required permissions. 
+
+## 2. Components & UI Design
+*Explored by the Components Researcher*
+
+- **Layered Architecture**: Organized into four groups inside `src/components`:
+  - `ui/`: Fundamental design blocks (shadcn/ui style with Radix and Tailwind).
+  - `common/`: Reusable composites like `DataTable` (using `@tanstack/react-table`), `PageHeader`, and loading/error states.
+  - `shell/`: The main application frame containing the sidebar, header, and global command palette.
+  - `features/`: The complex domain-specific pages (e.g., Wizards, Terminals) loaded by the Next.js router.
+- **Design System**: A robust, heavily customized "glassmorphic" Tailwind UI, using css variables and variants to construct glowing shadows, backdrops, and seamless transitions.
+- **Key Patterns**: Widespread use of client components (`"use client"`), dynamic lazy loading for heavy widgets like the Terminal (xterm.js) and charts, and TanStack React Query for data fetching.
+
+## 3. Architecture & Data Flow
+*Explored by the Architecture Researcher*
+
+- **State Management**: Uses Zustand (with persistence) centrally located at `src/stores/ui-store.ts`. Primarily tracks layout views (sidebar status) and complex appearance themes (accents, glass intensity, density).
+- **API Contracts**: Strong typing in `src/api/contracts/` for requests, responses, pagination, and data models (e.g., User, Website, Database, Backup).
+- **Mock Services**: Because this is a frontend-only control center template, data access occurs through a mock client (`src/api/client.ts`) that simulates network latency and errors. Rich placeholder data is generated by `src/api/mocks/seed.ts` (using `date-fns`), which feeds into the simulated endpoints in `src/api/services/panel-service.ts`.
+- **Utilities**: Employs `clsx` and `tailwind-merge` for style class merging, along with robust date utilities.
+
+---
+*Generated autonomously via specialized subagents.*

README.md

@@ -0,0 +1,133 @@
+# 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/*`.

backend/tests/e2e/README.md

@@ -0,0 +1,44 @@
+# CoaxysPanel REST API E2E Test Suite
+
+This directory contains the comprehensive, opaque-box E2E test suite for the CoaxysPanel REST API.
+
+The test suite validates:
+- **Tier 1 (Happy Paths)**: Basic CRUD on Auth, Websites, Domains, DNS, and general JSON API envelope compliance.
+- **Tier 2 (Boundaries & Negative States)**: Validation failures, conflicts (409), rate limiting, not found (404), method checks (405), server errors (500), and SQL injection safety.
+- **Tier 3 (Cross-Feature logic)**: Session expiration vs CRUD access, role-based scope comparison, and domain deletion mapping effects.
+- **Tier 4 (Real-World Workload)**: Complete lifecycle scenarios (login -> domain create -> website create -> configure -> clean up -> logout).
+
+## Configuration
+
+The test suite communicates with the backend via HTTP and is configured using environment variables.
+
+*   `API_URL`: The base URL of the CoaxysPanel REST API (defaults to `http://localhost:3001`).
+*   `DEBUG_E2E`: Set to `true` to enable verbose request and response logging for easier debugging.
+
+### Automatic Fallback Mock Server
+
+If no active server is detected at `API_URL`, or if the port is occupied by the Nova Telegram bot service, the global setup will **automatically start a local mock backend server** on port `3009` and override `API_URL` to point to it. This allows the E2E tests to be completely self-contained and runnable out of the box.
+
+## Commands
+
+### Typecheck Compilation
+
+Verify that the TypeScript test files compile cleanly:
+
+```bash
+npx tsc --noEmit
+```
+
+### Running the E2E Test Suite
+
+To run all E2E specs using Vitest:
+
+```bash
+npx vitest run --config backend/tests/e2e/vitest.config.ts
+```
+
+To run the E2E tests with debug request/response logging:
+
+```bash
+DEBUG_E2E=true npx vitest run --config backend/tests/e2e/vitest.config.ts
+```

docs/architecture.md

@@ -0,0 +1,7 @@
+# Architecture
+
+CoaxysPanel uses a registry-driven frontend architecture. `src/lib/routes.ts` defines navigable modules, sidebar entries, permissions, command-palette targets, tool cards, and page metadata.
+
+Interactive pages are composed from focused feature components. The catch-all panel route resolves known static and dynamic hosting-control paths into functional pages, avoiding dead links while keeping implementation maintainable.
+
+Client state is limited to global UI state in Zustand: sidebar state, theme, density, favorites, recent routes, and command-palette visibility. Server-like data is loaded through TanStack Query from typed mock services.

docs/backend-integration.md

@@ -0,0 +1,12 @@
+# Backend Integration
+
+The frontend is intentionally backend-ready but backend-free.
+
+Integration steps:
+
+1. Implement an HTTP client in `src/api/client.ts`.
+2. Replace mock methods in `src/api/services/panel-service.ts` with real service calls.
+3. Preserve the response envelope and DTOs in `src/api/contracts`.
+4. Map backend validation errors into `ApiError.fields`.
+5. Add WebSocket/SSE adapters for jobs, terminal state, notifications, metrics, and logs.
+6. Keep destructive actions behind typed confirmation, reason capture, two-factor confirmation, and audit-preview flows.

docs/design-system.md

@@ -0,0 +1,15 @@
+# Design System
+
+The design uses original CoaxysPanel branding: clean white/light-gray surfaces, thin borders, restrained shadows, strong blue primary accents, and sparing orange highlights.
+
+Tokens live in `src/lib/design-tokens.ts` and `src/app/globals.css`:
+
+- Colors and status colors
+- Typography defaults
+- Border radii
+- Sidebar and header sizing
+- Focus rings
+- Compact and comfortable density hooks
+- Table and form spacing conventions
+
+The UI intentionally favors dense operational screens over marketing layouts.

docs/frontend-api-contracts.md

@@ -0,0 +1,33 @@
+# Frontend API Contracts
+
+Contracts are defined in `src/api/contracts`.
+
+Every service returns:
+
+```json
+{
+  "data": {},
+  "meta": {
+    "requestId": "req_..."
+  },
+  "error": null
+}
+```
+
+Errors return:
+
+```json
+{
+  "data": null,
+  "meta": {
+    "requestId": "req_..."
+  },
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable message",
+    "fields": {}
+  }
+}
+```
+
+Shared DTOs cover pagination, filtering, sorting, bulk operations, jobs, job progress, audit metadata, permission checks, and WebSocket events.

docs/permissions.md

@@ -0,0 +1,5 @@
+# Permissions
+
+Permissions live in `src/lib/permissions.ts`. Routes declare required permissions, and the shell/page renderer can show permission-denied states.
+
+Initial roles include Super administrator and Read-only auditor. The roles screen exposes a detailed permission matrix covering every module and is ready to connect to a backend RBAC API.

docs/testing.md

@@ -0,0 +1,10 @@
+# Testing
+
+Unit and component tests use Vitest and React Testing Library:
+
+- Service response envelopes
+- Store behavior
+- Resource meters
+- Data table filtering
+
+Playwright flows cover login, dashboard navigation, tool search, website wizard validation, DNS editor, file manager actions, database/email entry points, backup/security screens, and theme switching.