diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0f9efc9
--- /dev/null
+++ b/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/*`.