bhooai-nexus 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BhooAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,184 +1,289 @@
 # BhooAI Nexus
 
-A Node-based full-stack framework: websockets, GraphQL federation (no Apollo), inbuilt CSRF/CORS, a from-scratch ODM on the MongoDB driver, Google/Facebook OAuth, five payment gateways, email, public/private certificate generation, Redis cache, Google Ads, WebRTC live streaming, a Python AI server (OpenAI + Ollama), an admin project, and a plugin system — all driven by a single `nexus.config.ts` and a `/bin` CLI.
+Build full-stack Node.js applications with one CLI and one configuration file. BhooAI Nexus includes an HTTP server, WebSockets, GraphQL federation, MongoDB data access, authentication, CSRF/CORS protection, payments, email, WebRTC, Python AI services, plugins, an admin console, and master/slave cluster orchestration.
 
-This directory is the package and workspace root. Its `package.json` and
-`package-lock.json` live here; the parent `BhooAI-Nexus/` directory is only a
-container and is not an npm project.
+## Features
 
-The `apps/admin/` panel is built into this package and shared by every project created
-with `nexus init`. Generated projects only contain a launcher; the common panel
-source remains owned by this package.
+- Node.js HTTP server with trie routing, middleware, uploads, static files, security headers, CORS, CSRF, and rate limiting
+- MongoDB ODM with schemas, hooks, indexes, populate, and transactions
+- JWT access tokens, refresh tokens, sessions, Google OAuth, Facebook OAuth, and role-based access control
+- WebSockets, Redis adapters, WebRTC signaling, and mediasoup SFU integration
+- GraphQL subscriptions, federation composition, entity joins, `@provides`, and `@requires`
+- Razorpay, PayPal, PayU, Skrill, and Payoneer integrations
+- Email, certificate generation, Redis cache, Google Ads, and plugin extensions
+- Python FastAPI AI server with OpenAI-compatible chat, embeddings, Ollama, and SSE streaming
+- Admin console with configuration, environment, process, monitoring, database, AI, and cluster management
+- Master/slave cluster mesh with load balancing, node agents, request allocation, health checks, and upload path pinning
+- Tailwind CSS + `@bhooai/nexus-postcss` preset with PostCSS pipeline, design tokens, and dark theme baseline for every scaffolded frontend
 
-## Layout
+## Requirements
 
-```
-packages/   scoped framework packages (@bhooai/nexus-*)
-apps/       backend (Node), frontend (React+Vite+Tailwind), ai-server (Python FastAPI)
-apps/admin/ admin project (React+Vite+TS) — manages config, plugins, the user project
-bin/        CLI entry — `node bin/nexus.js <command>`
-contracts/  Node↔Python contract (single source of truth)
-plugins/    user-created plugins
-tests/      cross-service e2e (Playwright) driving the real backend
-logs/ certs/ generated at runtime (gitignored)
-```
-
-## Quick start
+- Node.js `>=20.10`
+- npm, included with Node.js
+- MongoDB 7 or newer, running locally or reachable through `MONGODB_URI`
+- Redis 7 or newer, running locally or reachable through `REDIS_URL`
+- Python 3.10 or newer for the optional AI server
+- A virtual environment is recommended for Python dependencies
 
-```bash
-npm install              # install workspaces
-npm run doctor           # verify node/python/mongo/redis
-npm run dev              # start the four terminals under the supervisor
-npm test                 # vitest (Node) + pytest (Python)
-```
+The Python service dependencies are listed in [`apps/ai-server/requirements.txt`](apps/ai-server/requirements.txt): FastAPI, Uvicorn, HTTPX, pytest, and pytest-asyncio.
 
-## Use as an npm package
+MongoDB and Redis can be started with Docker, system services, or managed cloud providers. The AI server is optional when AI features are not used.
 
-Publish the public workspace packages together from the framework repository:
+## Install
 
 ```bash
-npm publish
+npm install bhooai-nexus
+npx nexus init my-app
+cd my-app
+npm run doctor
+npm run dev
 ```
 
-Then a new app can be created without copying the framework repository:
+Initialize the current directory with `npx nexus init .`. Use `npx nexus init . --skip-install` to defer dependency installation.
+
+## Quick Start
 
 ```bash
-mkdir my-app
+npm install bhooai-nexus
+npx nexus init my-app
 cd my-app
-npm init -y
-npm install C:\server\BhooAI\BhooAI-Nexus\BhooAI-Nexus\bhooai-nexus
-npx nexus init .
 npm run doctor
 npm run dev
 ```
 
-`bhooai-nexus` installs the `nexus` executable. `nexus init` copies the backend, frontend, AI,
-admin, config, and `uploads/` scaffold into the current directory, then automatically runs
-`npm install` for React, Vite, the admin workspace, and framework packages. Use
-`nexus init . --skip-install` when dependency installation should be deferred.
+Default development services:
+
+| Service | Default port |
+| --- | ---: |
+| Backend API | `4000` |
+| Frontend | `3000` |
+| Admin console | `3300` |
+| Python AI server | `8000` |
+| Cluster load balancer | `8080` |
+| Node agent | `7575` |
+
+`nexus dev` automatically moves a configured port to the next available port, allowing master and slave projects to run side by side on one machine.
+
+## Screenshots
+
+### Admin login
+
+![BhooAI Nexus admin login](docs/screenshots/login.png)
+
+### Overview dashboard
+
+![BhooAI Nexus overview dashboard](docs/screenshots/overview.png)
+
+### Master cluster management
+
+![BhooAI Nexus master cluster management](docs/screenshots/cluster-master.png)
+
+### Slave node agent and roles
+
+![BhooAI Nexus slave node agent](docs/screenshots/cluster-slave.png)
+
+### Connected cluster nodes
+
+![Connected cluster nodes](docs/screenshots/cluster-nodes.png)
+
+### AI agents
+
+![AI agents](docs/screenshots/ai-agents.png)
+
+### AI providers
+
+![AI agent providers](docs/screenshots/ai-agents-providers.png)
+
+### AI playground
+
+![AI playground](docs/screenshots/ai-agents-playground.png)
+
+### Monitoring
+
+![Monitoring dashboard](docs/screenshots/monitoring.png)
+
+### Settings
+
+![Settings](docs/screenshots/settings.png)
+
+### Themes
+
+![Theme selection](docs/screenshots/themes.png)
+
+### Appearance
+
+![Appearance settings](docs/screenshots/appearance.png)
+
+### Search
+
+![Admin search](docs/screenshots/search-bar.png)
+
+### Notifications
+
+![Notifications](docs/screenshots/notification.png)
+
+### AI log summary
+
+![AI log summary](docs/screenshots/logs-ai-summary.png)
+
+### Nexus development services
+
+![Nexus development services](docs/screenshots/nexus-dev.png)
+
+### Nexus initialization
+
+![Nexus initialization](docs/screenshots/nexus-init.png)
 
-Four terminals boot under one supervisor: backend (`:4000`), frontend (`:3000`),
-admin (`:3001`), and the Python AI server (`:8000`). Each is also runnable standalone.
+## Cluster Mesh
 
-## Scaffold a new project
+BhooAI Nexus supports a central master and one or more slave nodes.
+
+Initialize a master:
 
 ```bash
-node bin/nexus.js init ./my-app
-cd my-app
-npm run doctor   # check the environment
-npm run dev      # start all four terminals
+npx nexus init master --as=root
+```
+
+Initialize a slave with a built-in role:
+
+```bash
+npx nexus init slave-1 --as=node --role=backend --port=7575
+npx nexus init slave-2 --as=node --role=files --port=7576
 ```
 
-`init` copies a real, runnable project tree from `packages/nexus-cli/templates/`
-— the generated backend boots a Nexus HTTP server with the full security stack
-(CSRF/CORS/security headers) and serves `/health`, `/csrf-token`, `/echo`, and the CSRF-protected
-multipart upload endpoint `/uploads`. Uploaded files are stored below the project-local `uploads/`
-directory and served at `/uploads/<generated-name>`.
+Supported node roles are `backend`, `files`, `database`, and `ai`.
+
+After `npm run dev`, a node project automatically starts its node agent. The agent exposes the control API and advertises the node's development backend without starting a duplicate backend process.
+
+The master load balancer listens on port `8080` and distributes traffic across ready backend nodes. Authentication routes are pinned to the master:
+
+- `/auth/*`
+- `/csrf-token`
+
+Use the same `NEXUS_AUTH_JWT_SECRET` on all nodes so slaves can verify master-issued access tokens.
+
+### Upload path allocation
+
+The master admin console includes **Cluster → Path routing**. Pin URL prefixes to specific nodes:
+
+```text
+/uploads/images  ->  slave-1
+/uploads/files   ->  slave-2
+```
+
+Path pins use longest-prefix matching. A pinned request is sent only to its configured node. If the pinned node is unavailable, the load balancer returns `503 pinned_node_down` instead of silently sending the request to another node.
+
+When no slave nodes are linked, the load balancer fails open to the master's own backend if `cluster.failOpenSingleNode` is enabled. This keeps a cluster-enabled master usable as a single-node installation.
+
+Upload endpoints accept both `/uploads` and sub-paths such as `/uploads/images`. The upload directory is created automatically on the node that handles the request.
+
+## Admin Console
+
+Open the admin console at `http://localhost:3300` during development. The console provides overview, processes, logs, configuration, environment, plugins, users, monitoring, payments, databases, schema, AI, and cluster management.
+
+The Cluster tab includes connected-node cards with request allocation percentage, CPU, memory, freshness, service health, test, enable, restart, and unlink controls. Slave mode includes role selection, node-agent status, pairing tokens, node IDs, and copyable serve/link commands. Master mode includes path-prefix routing for uploads and other services.
 
 ## Configuration
 
-Edit `nexus.config.ts`. Precedence (low → high): code defaults < `nexus.config.ts`
-< `nexus.runtime.json` (admin write-back, gitignored) < env vars < CLI flags.
-Put secrets directly in a project-root `.env` (no `.env.example` — the framework
-loads `.env` itself). Admin overrides write only to
-`nexus.runtime.json` so the human config file stays clean.
-
-## Admin console
-
-The admin app (`apps/admin/`, Vite on `:3001`, backend-adjacent) is an `admin`-role
-login gate plus a glass dashboard. Overview, Processes, Configuration, Environment,
-Plugins, Users, Monitoring, Payments, Databases, and AI Schema.
-
-- **Theme & mode** — three themes (Aurora, Midnight, Violet) and three interface
-  modes (Workspace, Compact, Focus), persisted in browser local storage and applied
-  to the login screen too. Desktop shell is a fixed 80% of the actual screen width;
-  responsive down to a full-width mobile drawer.
-- **Configuration** — grouped key/value editor (add-key box on top, autoloads the
-  current config) writing to `nexus.runtime.json`, plus an effective merged view
-  and a raw source editor for `nexus.config.ts`.
-- **Environment** — masked grouped key/value editor for `.env`; secrets stay on
-  disk and are never returned to the browser.
-- **Safety** — custom restart-required dialog after config/env saves and a
-  confirmation dialog for destructive database/collection drops; writes are
-  schema-validated with atomic file replacement.
-
-See [`apps/admin/README.md`](apps/admin/README.md) for full details and routes.
-
-## Testing & CI
-
-- **Unit/integration:** `npx vitest run` across all workspace packages (real MongoDB
-  via `.env`; Redis optional). Frontend client tests run under `apps/frontend`.
-- **Python:** `pytest` in `apps/ai-server` (FastAPI contract tests).
-- **E2E:** `npx playwright test --config=playwright.config.ts` boots the real backend
-  on a throwaway port + DB and drives auth → CSRF → GraphQL → payments end to end.
-- **CI:** `workflows/ci.yml` runs a **Linux** job (full suite with Mongo + Redis
-  service containers, pytest, Playwright e2e) and a **Windows** job (build, the
-  Mongo/Redis-free unit suites, frontend tests, and `nexus init`/`doctor` verification).
+Edit `nexus.config.ts`. Configuration precedence is:
 
-## Documentation
+```text
+code defaults < nexus.config.ts < nexus.runtime.json < NEXUS_* environment variables < CLI flags
+```
 
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — full architecture, data flow, and
-  component deep-dives (federation, ODM, plugins).
-- [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md) — improvements made during the build,
-  28 suggested next steps, and an honest seams table.
-- Per-package READMEs under `packages/nexus-*/README.md`.
-- [`apps/admin/README.md`](apps/admin/README.md) — admin console UI, theme, and config/env editing.
+Admin changes are written to the gitignored `nexus.runtime.json` file. Store secrets in the project `.env` file:
 
-## Status — complete (12/12 phases)
+```env
+MONGODB_URI=mongodb://localhost:27017/my-app
+REDIS_URL=redis://localhost:6379
+NEXUS_AUTH_JWT_SECRET=replace-with-a-long-random-secret
+```
 
-- ✅ Phase 0 — Foundations (config loader + precedence, DI, telemetry, CLI doctor/init, supervisor)
-- ✅ Phase 1 — HTTP + Security (custom `node:http` server, trie router, CSRF/CORS/headers/rate-limit)
-- ✅ Phase 2 — Data layer (custom ODM on the `mongodb` driver — schemas, hooks, populate, transactions, indexes)
-- ✅ Phase 3 — Auth (local JWT+refresh+sessions, Google + Facebook OAuth2, CSRF on auth + WS upgrade)
-- ✅ Phase 4 — Realtime + WebRTC signaling (WS rooms, Redis adapter, WS auth, mediasoup SFU)
-- ✅ Phase 5 — GraphQL (single subgraph, `_service`/`_entities`, subscriptions over WS)
-- ✅ Phase 6 — Federation (composition, supergraph SDL, query planner, entity joins, `@provides`/`@requires`)
-- ✅ Phase 7 — Payments (Razorpay + PayPal full, PayU/Skrill/Payoneer happy-path) + Email + Crypto (keypair/X.509/CSR) + Cache + Ads
-- ✅ Phase 8 — Plugins (trusted in-process + sandboxed worker_threads, capability policy, admin extensions)
-- ✅ Phase 9 — Python AI server (FastAPI, OpenAI + Ollama, SSE) + Node AI client
-- ✅ Phase 10 — Admin + supervisor (process control API, config editor → runtime.json, plugins, users, monitoring)
-- ✅ Phase 11 — Frontend (React + Vite + Tailwind; auth UI, non-Apollo graphql client, WS client, checkout, live-stream viewer)
-- ✅ Phase 12 — Hardening, docs, e2e, release (Playwright e2e, Win+Linux CI, `nexus init` upgrade, docs)
+Common port overrides include `NEXUS_SERVER_PORT`, `NEXUS_FRONTEND_PORT`, `NEXUS_ADMIN_PORT`, `NEXUS_CLUSTER_LBPORT`, `NEXUS_CLUSTER_NODEAGENTPORT`, and `AI_PORT`.
 
-## Dependency policy
+## Uninstall
 
-Built from scratch where it matters: **no Apollo**, **no mongoose**, **no express**.
-Allowed: `graphql` (graphql-js core), `mongodb`, `ws`, `nodemailer`, `node-redis`,
-`bcrypt`, `jose`, `mediasoup`/`mediasoup-client`, `google-ads-api`. The federation
-layer, ODM, HTTP server, and plugin sandbox are all hand-rolled.
+Preview changes:
 
+```bash
+npx nexus uninstall --dry-run
+```
 
-## Docker Windows
+Remove the project database and registration while keeping files:
 
-In project directory, open PowerShell and run:
 ```bash
-`.\docker.ps1 run`          # start the container
-`.\docker.ps1 build`        # build the image first
-`.\docker.ps1 run -f`       # start + follow logs
-`.\docker.ps1 logs`         # tail logs
-`.\docker.ps1 stop`         # stop container
-`.\docker.ps1 rm`           # stop + remove
+npx nexus uninstall
 ```
 
-Or from cmd:
+Remove the database, registration, and project directory:
+
 ```bash
-`docker.bat build`
-`docker.bat run`
+npx nexus uninstall --purge
 ```
 
-Note: if PowerShell blocks it, allow first with:
-Set-ExecutionPolicy -Scope Process Bypass
-After run, access: 
-```ps1
-  frontend  http://localhost:3000
-  admin     http://localhost:3001
-  backend   http://localhost:4000/health
+Skip confirmations or keep the database:
+
+```bash
+npx nexus uninstall --purge --force
+npx nexus uninstall --keep-db
+```
+
+Uninstall does not remove the framework package, MongoDB's `nexus_projects` database, or other projects.
+
+## Project Layout
+
+```text
+packages/       Framework packages (@bhooai/nexus-*)
+apps/backend/   Node.js backend
+apps/frontend/  React + Vite frontend
+apps/admin/     React + Vite admin host
+apps/ai-server/ Python FastAPI AI service
+bin/            CLI entry point
+contracts/      Node-to-Python API contracts
+plugins/        Project plugins
+tests/          Cross-service tests
+docs/           Architecture, improvements, and screenshots
+```
+
+## Testing
+
+```bash
+npx vitest run
+cd apps/ai-server
+python -m pip install -r requirements.txt
+pytest
 ```
 
-## Docker Linux
+Run Playwright end-to-end tests from the framework root:
 
 ```bash
-cd project-directory
-./docker.sh build
-./docker.sh run
+npx playwright test --config=playwright.config.ts
 ```
+
+## Docker
+
+```powershell
+.\docker.ps1 build
+.\docker.ps1 run
+.\docker.ps1 logs
+.\docker.ps1 stop
+```
+
+Development endpoints are frontend `http://localhost:3000`, admin `http://localhost:3300`, and backend `http://localhost:4000/health`.
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture and data flow
+- [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md) — improvement history
+- [`docs/troubleshooting.html`](docs/troubleshooting.html) — common errors and fixes
+- [`docs/screenshots/README.md`](docs/screenshots/README.md) — screenshot catalog
+- [`apps/ai-server/README.md`](apps/ai-server/README.md) — Python AI service
+- Package documentation under `packages/nexus-*/README.md`
+
+## Design Principles
+
+BhooAI Nexus avoids Apollo, Express, and Mongoose where direct control is required. The HTTP server, trie router, ODM, federation layer, and plugin sandbox are implemented in the workspace. Established libraries are used for standards and infrastructure, including GraphQL.js, MongoDB, Redis, WebSockets, Nodemailer, Jose, and mediasoup.
+
+## License
+
+BhooAI Nexus is released under the [MIT License](LICENSE).

package/apps/admin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bhooai/admin-host",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": true,
   "type": "module",
   "scripts": {
@@ -13,13 +13,11 @@
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
+    "@bhooai/nexus-postcss": "*",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.0",
-    "autoprefixer": "^10.4.20",
-    "postcss": "^8.4.47",
-    "tailwindcss": "^3.4.13",
     "typescript": "^5.6.2",
     "vite": "^5.4.0"
   }
-}
+}

package/apps/admin/postcss.config.js

@@ -1,6 +1,5 @@
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-};
+import { createPreset } from '@bhooai/nexus-postcss';
+
+export default createPreset({
+  extraContent: ['../../packages/nexus-admin/src/**/*.{ts,tsx}'],
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,154 @@
+# BhooAI Nexus — Architecture
+
+BhooAI Nexus is a source-first full-stack framework. A typed config file (`nexus.config.ts`), a project-root `.env`, and the `/bin` CLI drive four services under one supervisor: a Node backend, a React+Vite frontend, a Python (FastAPI) AI server, and a React admin app.
+
+## Repository shape (npm workspaces)
+
+```
+BhooAI-Nexus/                      (container; no package.json)
+└── bhooai-nexus/                  package/workspace root
+    ├── package.json               workspaces root: packages/*, apps/*, admin
+    ├── package-lock.json          workspace lockfile
+    ├── bin/nexus.js                   CLI entry (loads @bhooai/nexus-cli via tsx, no build step)
+    ├── nexus.config.ts                framework reference config
+    ├── nexus.runtime.json             gitignored — admin write-back overrides
+    ├── contracts/ai-openapi.yaml      Node↔Python AI contract (single source of truth)
+    ├── packages/                      14 scoped framework packages
+    │   ├── nexus-core        http (node:http, no express), router, middleware, config, DI
+    │   ├── nexus-telemetry    structured logger, metrics, request/trace IDs
+    │   ├── nexus-auth         CORS, CSRF, security headers, rate limit, JWT, OAuth, RBAC
+    │   ├── nexus-data         custom ODM on the mongodb driver (no mongoose)
+    │   ├── nexus-graphql      graphql-js + custom federation/gateway (no Apollo)
+    │   ├── nexus-realtime     WS server, rooms, Redis pub/sub, WebRTC signaling, mediasoup SFU
+    │   ├── nexus-payments     PaymentProvider + Razorpay/PayPal/PayU/Skrill/Payoneer + webhooks
+    │   ├── nexus-email        SMTP (nodemailer) + templates + queue
+    │   ├── nexus-crypto       RSA/EC keypair, X.509 self-signed, CSR (hand-rolled DER)
+    │   ├── nexus-cache        Redis wrapper + cache-aside + rate-limit backend
+    │   ├── nexus-ads          Google Ads REST client (GAQL)
+    │   ├── nexus-ai-client    Node client for the Python AI server (SSE, retries, timeout)
+    │   ├── nexus-plugins      plugin runtime: manifest, host, sandbox, hooks
+    │   ├── nexus-postcss      opinionated PostCSS preset (Tailwind, nesting, preset-env, autoprefixer, cssnano) + theme.css design tokens
+    │   └── nexus-cli          init, dev (supervisor), build, test, doctor
+    ├── apps/
+    │   ├── backend/           user backend built on @bhooai/nexus-* (modules + plugins)
+    │   ├── frontend/          React+Vite+TS+Tailwind user-facing app
+    │   └── ai-server/         Python FastAPI: OpenAI + Ollama
+    ├── apps/admin/            admin app (React+Vite+TS) — grouped key/value config + env editors (themed, responsive), database/process control, plugins, users, monitoring
+    ├── plugins/               user plugins (self-contained dirs with plugin.json)
+    └── tests/                 cross-service Playwright e2e
+```
+
+### Frontend CSS pipeline
+
+Both `apps/frontend` and `apps/admin` use Tailwind CSS via the framework-owned
+`@bhooai/nexus-postcss` preset. The preset (`packages/nexus-postcss/src/plugins.js`)
+loads six PostCSS plugins in order: `postcss-import` → `postcss-nested` → `tailwindcss`
+→ `postcss-preset-env` (stage 2) → `autoprefixer` → `cssnano` (production only). A
+`theme.css` stylesheet (`packages/nexus-postcss/src/theme.css`) defines 22 CSS custom
+properties (`--nexus-bg`, `--nexus-ink`, `--nexus-surface`, `--nexus-accent`, etc.) on
+`:root`, plus 15 `--admin-*` aliases for backwards compatibility. Scaffolded projects
+import the tokens with `@import '@bhooai/nexus-postcss/theme.css'` at the top of their
+`index.css`.
+
+Run workspace commands from `bhooai-nexus/`. The parent directory only groups
+the package and related local projects.
+
+## Four terminals = one supervisor + control API
+
+`bin/nexus.js dev` runs a custom supervisor (not `concurrently`/`pm2`) that owns the four child processes:
+
+1. `apps/backend` (tsx watch) — :4000
+2. `apps/frontend` (vite) — :3000
+3. `apps/ai-server` (uvicorn --reload) — :8000
+4. `apps/admin/` (vite) — :3001
+
+The supervisor streams prefixed colored logs, handles graceful Ctrl-C, and exposes a **localhost HTTP control API** on :7474 (`GET /status`, `POST /start?name=...`, `POST /restart?name=...`, `POST /stop?name=...`, `GET /logs?name=...`, CORS-enabled). On Windows, stop/restart terminates the complete child process tree. Each process is also runnable standalone.
+
+## Config precedence
+
+Low → high: **code defaults < framework config < user `nexus.config.ts` < `nexus.runtime.json` (admin, gitignored) < `.env` / env vars < CLI flags.**
+
+`@bhooai/nexus-core/config` loads the project `.env`, validates with zod, deep-merges, and exposes a typed object. The admin app writes **only `nexus.runtime.json`** so the human `nexus.config.ts` stays clean (no AST patching). Sections: server, uploads, db, redis, graphql, ws, auth, payments, email, certs, ads, webrtc, ai, plugins, logging.
+
+## Request lifecycle (backend)
+
+```
+HTTP request
+  → NexusServer (node:http)            securityHeaders → cors → static /uploads → bodyParser → csrf → rateLimit → router
+  → Router (trie: params/wildcard/405)  per-route middleware: [authToken, requireRole, ...] then handler
+  → handler(ctx)                       ctx.body (JSON/urlencoded/multipart), ctx.state.user, ctx.json/ctx.res
+  → Server sends 404 if !ctx.res.writableEnded
+```
+
+`ctx.res` is the raw `ServerResponse` (used directly for SSE streaming: `writeHead` + `write` + `end`). Raw body is retained on `ctx.state.__rawBody` for webhook signature verification.
+
+### File uploads
+
+`bodyParser` buffers multipart requests and exposes `ctx.state.files`. The backend registers
+`registerUploadRoutes` at `POST /uploads`; files are validated, renamed with generated UUID-based names,
+and written below the configured project-local `uploads.dir`. `serveStatic` mounts that directory read-only
+under `uploads.path`. The default request envelope is 12 MiB, the per-file limit is 10 MiB, and CSRF remains
+enforced by the normal middleware pipeline. Projects should set `uploads.allowedTypes` and authentication
+middleware for their own security requirements.
+
+## Security (nexus-auth — one cohesive unit)
+
+- **CORS**: preflight short-circuit, credentials, `Vary: Origin`.
+- **CSRF**: double-submit token (HttpOnly cookie `nexus_csrf` + `x-csrf-token` header); safe methods mint a fresh token, unsafe methods do `checkOrigin` (trustedOrigins non-empty → 401 on missing/untrusted Origin) + double-submit match. **CSRF is also enforced on the WS upgrade** (query/`Sec-WebSocket-Protocol`) since WS has no CORS preflight.
+- **Auth**: local (bcryptjs, JWT access+refresh rotation, httpOnly session cookies, Redis session store with reuse detection), Google (PKCE) + Facebook OAuth2 (state, token exchange, account linking), RBAC (role inheritance). First registered user is bootstrapped as admin.
+- **Rate limiting**: fixed-window; in-memory now, Redis-backed in production.
+
+## GraphQL (no Apollo)
+
+`nexus-graphql` uses `graphql` (graphql-js) for parse/validate/execute. Composition, supergraph SDL, the query planner, and the gateway executor are ours — no `@apollo/*`, no `@graphql-tools/federation`.
+
+```
+defineSubgraph (SDL+resolvers, auto-wires _service/_entities, @key parse)
+  → createGateway
+      ├─ in-process: execute() against the built PUBLIC schema (federation directives stripped)
+      └─ federated:  composeSupergraph → queryPlanner → executeFederated (FetchNode DAG, @key joins, @provides/@requires)
+  → graphqlHttpHandler (POST/GET, introspection toggle) + SubscriptionServer (graphql-transport-ws over ws)
+```
+
+Federation subset (v1): `@key` (single + composite), `@external`, `@requires`, `@provides`, `@extends`, `_entities`, `_service { sdl }`. The app ships single-subgraph by default; `nexus add subgraph` opts into federation.
+
+## Data (custom ODM, no mongoose)
+
+`nexus-data` on the official `mongodb` driver. Self-contained validators (no zod). Connection/ConnectionManager, Schema (field opts incl. ref/refPath/select/immutable/expires/unique/index/transform), Model (find/findById/create/insertMany/update*/delete*/aggregate/bulkWrite/findOneAndUpdate), DocumentInstance (Proxy, save/remove/validate/populate, pre/post hooks, timestamps, strict, virtuals), chainable+thenable Query, batched multi-level populate, transactions (`withTransaction`). Auto-index creation at boot.
+
+## Realtime + WebRTC (nexus-realtime)
+
+- **WS server** (`ws`, noServer upgrade) with connection registry, room membership, pub/sub adapter (Memory + Redis for cross-instance fanout), auth on upgrade via `?token=`/subprotocol + optional CSRF origin check.
+- **WebRTC signaling relay** over WS (offer/answer/candidate — direct if same-instance, else published to `conn:<to>`).
+- **mediasoup SFU adapter** (lazy import, one worker/router-per-room, send/recv transports, produce/consume). The browser uses `mediasoup-client`; the frontend `stream.ts` wraps it over the realtime `media` action channel.
+
+## Plugins (nexus-plugins)
+
+Two modes: **trusted** (in-process, full Node API, dynamic-import entry) and **sandboxed** (`worker_threads` with capability-restricted RPC — real heap/event-loop isolation, crash can't take down the host).
+
+```
+PluginManifest { name, version, entry, mode, capabilities[], configSchema, hooks[], dependencies[] }
+PluginHost: load(dir) → topoSort by deps (cycle detection) → runLifecycle(install→init→start→stop, stop reverses)
+PluginContext: http/graphql/data/auth/realtime/scheduler/events/admin registrars (capability-gated in sandbox)
+capabilityPolicy: METHOD_CAPABILITY map + fs path-allowlist + net host-allowlist + authorize()
+AdminExtensions: registerPage/registerSlot → grouped pages + ordered slots
+```
+
+The sandbox bootstrap is plain `.mjs` (Node runs it directly in the worker, no TS loader). The host drives ALL lifecycle hooks including `install`. Documented v1 seams: sandboxed plugins can't add GraphQL subgraphs (resolvers aren't serializable); sandboxed middleware is a no-op.
+
+## Payments (nexus-payments)
+
+`PaymentProvider` interface (createOrder/capture/refund/getOrderStatus/verifyWebhook) with an injectable `HttpTransport` (tests inject mocks — no live gateways). Razorpay + PayPal are full; PayU/Skrill/Payoneer are happy-path + sandbox tests. `WebhookRouter` dispatches by `:provider` param with per-provider signature verification. Browser-facing `/payments/order` routes are auth+CSRF guarded; webhooks stay separate.
+
+## Cross-service contract (contracts/)
+
+`ai-openapi.yaml` (OpenAPI 3.1) is the single source of truth for the Node↔Python AI boundary. The Python FastAPI server and the Node `nexus-ai-client` both conform to it. The browser never talks to Python directly — Node proxies/re-emits SSE. Both OpenAI and Ollama speak the OpenAI-compatible API → one `OpenAICompatibleProvider` parameterised by `base_url`+`api_key`.
+
+## Telemetry (nexus-telemetry)
+
+Structured JSON logger (stdout + rotating file, child loggers, redaction), metrics registry (counters/histograms, `/metrics`), request/trace-ID propagation across Node→WS→Python. Admin monitoring consumes this.
+
+## Testing
+
+- **Vitest** per Node package (real MongoDB via `.env` — no embedded Mongo) + **pytest** for the AI server + **Playwright** for cross-service e2e.
+- Each phase ships runnable + tested. See `docs/IMPROVEMENTS.md` for honest seams and next steps.