Add CyberLux blueprint notes

Include the project blueprint alongside the hardened boot flow and site work so the repository reflects the full current design state.

Made-with: Cursor

blueprint.md

@@ -0,0 +1,181 @@
+# **Autonomous Scalable Deployment Framework – Blueprint**
+## **Shadow Network v2: 100‑Service Autonomous Ecosystem**
+
+### **1. Core Design Principles**
+- **Single‑Command Deployment** – `./deploy.sh` initiates the entire network.
+- **Procedural Generation** – Every execution generates a **unique, non‑reproducible** network of 100 sites.
+- **Zero‑Touch Operation** – Post‑launch autonomy with self‑healing, health monitoring, and automatic scaling.
+- **Centralized Dashboard** – All sites link back to the **master control panel** at the launch machine’s IP.
+
+### **2. System Architecture**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Master Dashboard                      │
+│  (http://<LAUNCH_IP>:3000) – Real‑time monitoring       │
+└─────────────────┬───────────────────────────────────────┘
+                  │ (orchestrates)
+     ┌────────────┼────────────┐
+     ▼            ▼            ▼
+┌─────────┐ ┌─────────┐ ┌─────────┐
+│Service 1│ │Service 2│ │Service N│
+│Site‑01  │ │Site‑02  │ │Site‑100 │
+└─────────┘ └─────────┘ └─────────┘
+```
+
+**Components:**
+- **Orchestrator** – Python/Go service that spawns and manages containers.
+- **Generator Engine** – Procedural‑content system that creates unique frontends.
+- **Health Monitor** – Continuous heartbeat & anomaly detection.
+- **Self‑Healer** – Automatically restarts failed services, regenerates damaged sites.
+- **Dashboard** – Next.js‑based central UI showing status, traffic, logs.
+
+### **3. Procedural Generation Engine**
+
+**Unique Dimensions Per Site:**
+1. **Visual Theme** – Randomly pick from 20+ CSS variable sets (cyberpunk, vaporwave, matrix, noir, etc.)
+2. **Layout Structure** – Grid, single‑page, multi‑column, full‑screen, etc.
+3. **Content Slots** – Fill with generative text (marketing copy, product listings, fake testimonials)
+4. **Functional Modules** – Rotate between “marketplace”, “game”, “lottery”, “search”, “forum”, etc.
+5. **Domain/Subdomain** – Assign a random sub‑identifier (`site‑{hash}.onion`)
+
+**Generation Seed:**
+```bash
+DEPLOY_SEED=$(date +%s)$(hostname)$(cat /dev/urandom | tr -dc 'a-f0-9' | head -c 12)
+```
+This ensures **no two deployments are identical**, even across different machines/users.
+
+### **4. Deployment Workflow**
+
+**Step‑by‑Step Execution:**
+1. **Dependency Check** – Ensure Docker, Node.js, Tor, Nginx are present.
+2. **Seed Generation** – Create a unique seed for this deployment.
+3. **Template Expansion** – Use the seed to generate 100 distinct site configurations.
+4. **Container Spawn** – Launch each site in an isolated Docker container (or Kubernetes pod).
+5. **Service Registration** – Register each site with the central dashboard.
+6. **Network Wiring** – Configure reverse‑proxy (Nginx) to route `*.onion` to appropriate containers.
+7. **Health‑Check Init** – Start monitoring daemon.
+8. **Dashboard Launch** – Bring up the master control panel.
+
+**Single‑Command Invocation:**
+```bash
+./deploy.sh --sites 100 --theme random --autoscale
+```
+
+### **5. Technology Stack**
+
+| Layer | Technology | Rationale |
+|-------|------------|-----------|
+| **Orchestration** | Docker Compose / Kubernetes (k3s) | Lightweight, scalable container management |
+| **Frontend** | Next.js + Tailwind CSS + Faker.js | Enables rapid generative UI creation |
+| **Procedural Engine** | Python + Jinja2 templates | Flexible, deterministic random generation |
+| **Reverse Proxy** | Nginx + Lua (OpenResty) | Dynamic routing, load‑balancing |
+| **Monitoring** | Prometheus + Grafana + Custom health‑checks | Real‑time metrics, alerting |
+| **Self‑Healing** | SupervisorD + custom watchdog scripts | Automatic restart on failure |
+| **Dashboard** | Next.js (separate instance) + WebSocket | Live updates, central control |
+
+### **6. Containerization Strategy**
+
+Each site runs as a **separate container**:
+- **Base Image:** `node:18‑alpine` + Next.js build.
+- **Unique Environment Variables:** `SITE_ID`, `THEME_SEED`, `MASTER_DASHBOARD_URL`.
+- **Volume Mounts:** Procedurally generated assets (`/public`, `/app`).
+- **Network:** Isolated bridge network; exposed via Nginx reverse‑proxy.
+
+**Example Docker‑Compose Snippet:**
+```yaml
+services:
+  site-001:
+    build: ./generator/output/site-001
+    environment:
+      - SITE_ID=001
+      - MASTER_DASHBOARD=http://${LAUNCH_IP}:3000
+    networks:
+      - shadownet
+  # ... repeat for 100 services
+```
+
+### **7. Central Dashboard Design**
+
+**Features:**
+- **Live Network Map** – Visual graph of all 100 sites, color‑coded by health.
+- **Traffic Analytics** – Requests/second, error rates, uptime.
+- **Procedural Seed Display** – Show the current deployment’s unique seed.
+- **Manual Overrides** – Ability to restart, regenerate, or kill specific sites.
+- **Log Aggregation** – Stream logs from all containers into a single view.
+
+**Dashboard URL:** `http://<LAUNCH_IP>:3000` (hard‑coded into each site’s navigation).
+
+### **8. Autonomous Operation & Self‑Healing**
+
+**Health Checks:**
+- HTTP `GET /health` endpoint on each site (returns 200 OK if alive).
+- Background monitor pings every 30 seconds.
+- **Failure Detection:** Three consecutive failures trigger remediation.
+
+**Remediation Actions:**
+1. **Restart Container** – `docker restart site‑XXX`
+2. **Regenerate Site** – If restart fails, re‑run generator with same seed and replace.
+3. **Notify Dashboard** – Log incident, update status.
+
+**Automated Scaling:**
+- If average CPU > 80% across network, spawn additional replicas of high‑load sites.
+- Scaling decisions are made by the orchestrator, not human intervention.
+
+### **9. Security & Anonymity Considerations**
+
+**Note:** This is a **simulation framework**, not a real dark‑net anonymity solution.
+
+- **Tor Hidden Services** – Each site can be given a `.onion` address via `torrc` configuration.
+- **No Real Data** – All user inputs are ephemeral, no persistence to disk.
+- **Firewall Rules** – Isolate the network from the host machine (Docker network isolation).
+- **Legal Disclaimer** – Clearly label the system as a fictional simulation.
+
+### **10. Implementation Roadmap**
+
+**Phase 1 (Foundation)**
+- Extend `start_network.sh` to support multi‑container generation.
+- Build procedural generator prototype (Python script).
+- Create a single‑site Dockerfile that accepts theme parameters.
+
+**Phase 2 (Scalability)**
+- Implement orchestration (Docker Compose) for 100 containers.
+- Develop central dashboard (Next.js) with WebSocket updates.
+- Integrate health‑check system.
+
+**Phase 3 (Autonomy)**
+- Add self‑healing watchdog.
+- Introduce load‑based auto‑scaling.
+- Polish UI/UX of dashboard.
+
+**Phase 4 (Deployment Polish)**
+- Package as a single‑command binary (`shadow‑deploy`).
+- Write comprehensive documentation.
+- Test across different host machines (Linux, macOS, WSL).
+
+### **11. Expected Output**
+
+After running `./deploy.sh`:
+- **100 unique websites** running on ports 31001‑31100 (or via `.onion` addresses).
+- **Master dashboard** at `http://<LAUNCH_IP>:3000` showing live status.
+- **Zero manual intervention** required – the network self‑sustains.
+- **Each site** includes a navigation link back to the master dashboard.
+
+### **12. Risks & Mitigations**
+
+| Risk | Mitigation |
+|------|------------|
+| **Resource exhaustion** (100 containers) | Use lightweight Alpine images; implement resource limits. |
+| **Seed collision** (identical networks) | Incorporate machine‑specific identifiers + high‑entropy random. |
+| **Dashboard single point of failure** | Run dashboard in redundant mode; embed fallback IP in sites. |
+| **Legal misinterpretation** | Add clear disclaimers; avoid realistic illicit content. |
+
+---
+
+## **Next Actions**
+1. Enhance `start_network.sh` to implement Phase 1.
+2. Build procedural generator (`generator/` directory).
+3. Create Dockerfile template.
+4. Implement dashboard aggregation.
+
+**This blueprint transforms the existing static simulation into a genuinely scalable, autonomous network of 100 unique, independently operating service websites.**