bhooai-nexus 2.0.4 → 2.0.6

package/README.md

@@ -1,8 +1,8 @@
-# BhooAI Nexus v2
+# BhooAI Nexus
 
 A production-ready Node.js full-stack framework. One config file, one CLI, multi-app monorepo.
 
-> v2 is a fresh workspace at `C:\server\PACKAGES\bhooai-nexus\` — reuses v1's packages, removes the
+> v2 is a fresh workspace — reuses v1's packages, removes the
 > cluster subsystem (Docker handles scaling), rewrites the CLI, and adds a Laravel-style
 > convention layer on top.
 
@@ -38,36 +38,121 @@ nexus init my-app --no-install
 
 ## Architecture at a glance
 
+N backends × N frontends, all discovered by a single admin SPA. Each backend is an isolated `createNexusApp()` instance with its own port, routes folder, storage root, and per-app config. Docker handles horizontal scaling — `docker compose up --scale backend-main=4` — so the v1 cluster subsystem (master/slave mesh, node agents, autoscaler, load balancer) is gone entirely.
+
+```
+┌─────────────────────── Docker Host ───────────────────────┐
+│                                                            │
+│  frontend(s)     Vite + React, served via Nginx            │
+│  admin           Vite + React, wraps @bhooai/nexus-admin   │
+│  ai-server       FastAPI :8000 (optional Python sidecar)   │
+│                                                            │
+│         ▲                  ▲                  ▲            │
+│         │                  │                  │            │
+│  ┌──────┴──────┐   ┌───────┴───────┐   ┌──────┴──────┐     │
+│  │ backend-main│   │ backend-shop  │   │ backend-…   │     │
+│  │   :4000     │   │   :4010       │   │  :4020+     │     │
+│  └──────┬──────┘   └───────┬───────┘   └──────┬──────┘     │
+│         │                  │                  │            │
+│         └──────────┬───────┴──────────────────┘            │
+│                    ▼                                       │
+│   ┌────────┬────────┬──────────┬─────────┬───────────┐     │
+│   │ MongoDB│ Redis  │ storage/ │ S3/CDN  │  queue    │     │
+│   └────────┴────────┴──────────┴─────────┴───────────┘     │
+│                                                            │
+│   .nexus-ports.json   ← stable port registry               │
+│   nexus.config.ts     ← single source of truth             │
+│   docker-compose.yml  ← orchestration                      │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Workspace layout
+
 ```
-┌──────────────── Multi-app monorepo ─────────────────┐
-│  apps/backend/        ← Node.js, auto-discovery      │
-│  apps/backend-shop/   ← add via `nexus add backend`  │
-│  apps/frontend/       ← Vite + React                 │
-│  apps/frontend-shop/  ← add via `nexus add frontend` │
-│  apps/admin/          ← wraps @bhooai/nexus-admin    │
-│  apps/ai-server/      ← FastAPI (optional)           │
-│  .nexus-ports.json    ← stable port registry         │
-│  nexus.config.ts                                      │
-│  docker-compose.yml                                   │
-└──────────────────────────────────────────────────────┘
+apps/
+├── backend/          Node.js backend — auto-discovery, createNexusApp()
+├── backend-shop/     add more backends via `nexus add backend <name>`
+├── frontend/         Vite + React
+├── frontend-shop/    add more frontends via `nexus add frontend <name> [--for <backend>]`
+├── admin/            wraps @bhooai/nexus-admin
+└── ai-server/        FastAPI sidecar (optional)
 ```
 
-Each backend follows a Laravel-style convention under `src/`:
+### Per-backend `src/` convention (Laravel-style)
+
+Each backend lives under `apps/<backend>/` and follows a flat, auto-discovered folder convention inspired by Laravel. `createNexusApp()` scans these folders at boot — no manual registration.
 
 ```
-src/
-├── main.ts              # 20-line createNexusApp()
-├── routes/              # HTTP endpoints (auto-discovered)
-├── graphql/             # *.graph.ts (federation)
-├── ws/                  # *.room.ts (WebSocket rooms)
-├── mail/templates/      # *.ejs
-├── mail/mailables/      # classes
-├── errors/pages/        # 404.html / 500.html / ...
-├── errors/Handler.ts
-├── models/ services/ repositories/ controllers/
-├── middleware/ validators/ jobs/ listeners/ events/
-├── policies/ resources/ requests/ helpers/ config/
-├── database/{seeds,migrations}/ providers/ plugins/ types/ constants/
+apps/<backend>/src/
+├── main.ts                  # 20-line createNexusApp() entry point
+│
+├── routes/                  # HTTP endpoints — *.ts, auto-discovered
+├── graphql/                 # Federated subgraphs — *.graph.ts → /graphql
+├── ws/                      # WebSocket rooms — *.room.ts → /ws
+│
+├── mail/
+│   ├── templates/           # *.ejs email templates
+│   └── mailables/           # classes extending Mailable
+│
+├── errors/
+│   ├── pages/               # 404.html · 500.html · 403.html · 503.html · maintenance.html
+│   └── Handler.ts           # global exception handler
+│
+├── models/                  # nexus-data ODM models (schemas, hooks, populate)
+├── services/                # business logic layer
+├── repositories/            # DB query layer (encapsulates ODM calls)
+├── controllers/             # optional route extraction (thin handlers)
+├── middleware/              # route-level middleware
+├── validators/              # zod schemas
+├── jobs/                    # queue jobs — *Job.ts
+├── listeners/               # event subscribers — On*.ts (auto-wired)
+├── events/                  # domain event classes
+├── policies/                # authorization rules — *Policy.ts
+├── resources/               # API response transformers — *Resource.ts
+├── requests/                # form-request classes — *Request.ts (validation + auth)
+├── helpers/                 # pure utilities
+├── config/                  # app-level config (NOT framework config)
+│
+├── database/
+│   ├── seeds/               # *Seeder.ts — via `nexus db:seed`
+│   └── migrations/          # <timestamp>_*.ts — via `nexus db:migrate`
+│
+├── providers/               # *ServiceProvider.ts — DI registration (register + boot)
+├── plugins/                 # project-local plugins — <name>/index.ts
+├── types/                   # shared TS types
+└── constants/               # app constants
+```
+
+**Auto-discovery map** — what `createNexusApp()` scans at boot:
+
+| Folder | Pattern | Mounted as |
+|---|---|---|
+| `routes/` | `*.ts` (`defineRoutes` default export) | HTTP routes (optional per-file prefix) |
+| `graphql/` | `*.graph.ts` | Federated supergraph under `/graphql` |
+| `ws/` | `*.room.ts` | WS rooms under `/ws` |
+| `mail/templates/` | `*.ejs` | Email rendering |
+| `mail/mailables/` | `*.ts extends Mailable` | Mailable classes |
+| `errors/pages/` | `<status>.html` | Error page lookups |
+| `errors/Handler.ts` | single file | Global exception handler |
+| `events/` | `*.ts` | Domain event classes |
+| `listeners/` | `On*.ts` | Auto-wired to matching events |
+| `jobs/` | `*Job.ts` | Queue jobs |
+| `policies/` | `*Policy.ts` | Authorization registry |
+| `providers/` | `*ServiceProvider.ts` | DI registrations (register + boot) |
+| `database/seeds/` | `*Seeder.ts` | `nexus db:seed` |
+| `database/migrations/` | `*.ts` | `nexus db:migrate` |
+| `plugins/<name>/index.ts` | folder | Local plugins |
+| `config/*.ts` | folder | Merged into app config |
+
+**Sibling `storage/`** (gitignored, per-backend):
+
+```
+apps/<backend>/storage/
+├── uploads/             # PUBLIC — served at GET /uploads/*
+├── private/             # signed-URL only — GET /files/:id?sig=…
+├── temp/                # multipart assembly chunks (cleaned up)
+├── cache/
+└── logs/
 ```
 
 ## CLI
@@ -131,6 +216,31 @@ Prefer narrower imports for smaller bundles? Use the sub-path exports
 (`bhooai-nexus/core`, `bhooai-nexus/data`, `bhooai-nexus/ai-client`, …) or the
 scoped packages (`@bhooai/nexus-core`, `@bhooai/nexus-data`, …) directly.
 
+## Packages
+
+18 workspace packages ship under `packages/`, each independently versioned and re-exported by the umbrella `bhooai-nexus` package.
+
+| Package | Scope | Import path | Purpose |
+|---|---|---|---|
+| nexus-admin | `@bhooai/nexus-admin` | `bhooai-nexus/admin` | Admin SPA — Apps-tab-first, live registry/health/logs/config/users/payments/AI |
+| nexus-ads | `@bhooai/nexus-ads` | — | Advertising module |
+| nexus-ai-client | `@bhooai/nexus-ai-client` | `bhooai-nexus/ai-client` | AI provider client (streaming, provider switching) |
+| nexus-auth | `@bhooai/nexus-auth` | `bhooai-nexus/auth` | Authentication (JWT, OAuth, sessions, refresh tokens) |
+| nexus-cache | `@bhooai/nexus-cache` | `bhooai-nexus/cache` | Caching layer (Redis-backed) |
+| nexus-cli | `@bhooai/nexus-cli` | `bhooai-nexus/cli` | CLI — init, dev, build, test, scaffolding, plugins, queue, db |
+| nexus-core | `@bhooai/nexus-core` | `bhooai-nexus/core` | Core — `createNexusApp()`, auto-discovery, HTTP, storage facade, abstractions |
+| nexus-crypto | `@bhooai/nexus-crypto` | `bhooai-nexus/crypto` | Cryptography utilities |
+| nexus-data | `@bhooai/nexus-data` | `bhooai-nexus/data` | Custom ODM for MongoDB (schemas, hooks, populate) |
+| nexus-email | `@bhooai/nexus-email` | `bhooai-nexus/email` | Email sending (Mailable classes, EJS templates) |
+| nexus-examples | `@bhooai/nexus-examples` | `bhooai-nexus/examples` | 10 working examples, each demoing a framework slice |
+| nexus-graphql | `@bhooai/nexus-graphql` | `bhooai-nexus/graphql` | GraphQL federation layer (subgraphs, supergraph) |
+| nexus-payments | `@bhooai/nexus-payments` | `bhooai-nexus/payments` | Payments (Razorpay, PayPal, HMAC webhook verify) |
+| nexus-plugins | `@bhooai/nexus-plugins` | `bhooai-nexus/plugins` | Plugin system (new/install/remove/list) |
+| nexus-postcss | `@bhooai/nexus-postcss` | `bhooai-nexus/postcss` | PostCSS preset — Tailwind, nesting, autoprefix, minify |
+| nexus-realtime | `@bhooai/nexus-realtime` | `bhooai-nexus/realtime` | WebSocket rooms, presence, typing |
+| nexus-safe-goto | `@bhooai/nexus-safe-goto` | `bhooai-nexus/safe-goto` | Safe external-link navigation (noopener/noreferrer, confirm dialog) |
+| nexus-telemetry | `@bhooai/nexus-telemetry` | `bhooai-nexus/telemetry` | Telemetry / observability |
+
 ## Maintenance mode
 
 ```
@@ -153,6 +263,7 @@ EJS templating. 27 tests, all green.
 
 - P0–P12 shipped (skeleton, app factory, abstractions, storage, CLI, plugins, db, queue,
   generators, port registry, examples, docker, admin strip + Apps tab)
+- 18 workspace packages under `packages/` (see § Packages above)
 - Admin rebuilt as a fresh Apps-tab-first SPA with live backend endpoints
   (registry, health, request logs, config, users, payments, AI proxy)
 - `bhooai-nexus` is the publishable main package — umbrella import + auto-installing init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bhooai-nexus",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "BhooAI Nexus - a Node-based full-stack framework (websockets, GraphQL federation, inbuilt security, custom ODM, OAuth, payments, WebRTC, AI, plugins). v2: multi-app, Laravel-style folders, Docker-based scaling.",
   "license": "MIT",
   "author": "BhooAI",

package/packages/nexus-admin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bhooai/nexus-admin",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "BhooAI Nexus v2 admin SPA — Apps-tab-first, live registry/health/logs/config/users/payments/AI",
   "type": "module",
   "license": "MIT",