NxMesh-old/README.md

# NxMesh - Distributed Nginx Management System

> **NxMesh** is a modern, scalable, distributed system for managing nginx instances across diverse infrastructure environments. Built with a master-agent architecture inspired by service mesh patterns, NxMesh provides centralized control with local intelligence.

## 🎯 Project Vision

NxMesh transforms nginx from a standalone reverse proxy into a **distributed, programmable edge layer**. By adopting a control plane (master) + data plane (agent/sidecar) architecture, NxMesh enables:

- **Centralized Management**: Control thousands of nginx instances from a single control plane
- **Dynamic Configuration**: Real-time configuration updates without restarts or connection drops
- **Observability**: Unified metrics, logs, and health status across the entire fleet
- **Hybrid Deployment**: Support for Docker, Kubernetes, VMs, and bare metal environments
- **High Availability**: Fault-tolerant design with automatic failover and recovery

## 🏗️ Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           CONTROL PLANE (Master)                                 │
│  ┌──────────────────────────────────────────────────────────────────────────┐   │
│  │                          NxMesh Master                                   │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │   API        │  │  Config      │  │  Cluster     │  │   Admin      │  │   │
│  │  │   Server     │  │  Manager     │  │  Coordinator │  │   Console    │  │   │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │   │
│  │         └──────────────────┴──────────────────┴──────────────────┘        │   │
│  │                              │                                             │   │
│  │                         PostgreSQL (State)                                │   │
│  └──────────────────────────────┼─────────────────────────────────────────────┘   │
│                                 │                                                 │
│                    gRPC/TLS     │    WebSocket (Events)                           │
│                                 ▼                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
        ▼                           ▼                           ▼
┌───────────────┐          ┌───────────────┐          ┌───────────────┐
│   AGENT 1     │          │   AGENT 2     │          │   AGENT N     │
│  (Sidecar)    │          │  (Standalone) │          │  (K8s Pod)    │
│ ┌───────────┐ │          │ ┌───────────┐ │          │ ┌───────────┐ │
│ │ NxMesh    │ │          │ │ NxMesh    │ │          │ │ NxMesh    │ │
│ │ Agent     │ │          │ │ Agent     │ │          │ │ Agent     │ │
│ └─────┬─────┘ │          │ └─────┬─────┘ │          │ └─────┬─────┘ │
│       │       │          │       │       │          │       │       │
│  ┌────┴────┐  │          │  ┌────┴────┐  │          │  ┌────┴────┐  │
│  │  Nginx  │  │          │  │  Nginx  │  │          │  │  Nginx  │  │
│  │ Instance│  │          │  │ Instance│  │          │  │ Instance│  │
│  └─────────┘  │          │  └─────────┘  │          │  └─────────┘  │
└───────────────┘          └───────────────┘          └───────────────┘
  Docker Compose              VM/Bare Metal              Kubernetes
```

### Core Components

| Component | Description | Technology |
|-----------|-------------|------------|
| **Master** | Central control plane - API, embedded Web UI, config distribution | Rust (Axum/gRPC) + Embedded Vite React |
| **Agent** | Local nginx controller - configuration, health checks, metrics | Rust (Tokio) |
| **Database** | Persistent state storage | PostgreSQL |

## 🚀 Key Features

### Phase 1: Foundation
- [ ] **Master Control Plane**
  - RESTful API for configuration management
  - gRPC for agent communication
  - PostgreSQL persistence
  - JWT-based authentication

- [ ] **Agent Sidecar**
  - Docker deployment mode (sidecar pattern)
  - Standalone deployment mode
  - Automatic nginx lifecycle management
  - Configuration hot-reloading

- [ ] **Configuration Management**
  - Virtual host (server block) templating
  - Upstream pool management
  - SSL/TLS certificate management
  - Configuration versioning & rollback

### Phase 2: Resilience
- [ ] **High Availability**
  - Master clustering with Raft consensus
  - Agent auto-reconnection with exponential backoff
  - Configuration drift detection & auto-healing

- [ ] **Observability**
  - Real-time metrics collection (Prometheus)
  - Structured logging (OpenTelemetry)
  - Health check dashboards
  - Alert management

### Phase 3: Advanced
- [ ] **Traffic Management**
  - Dynamic load balancing strategies
  - Circuit breaker patterns
  - Rate limiting & WAF rules
  - A/B testing & canary deployments

- [ ] **Multi-tenancy**
  - Organization/workspace isolation
  - RBAC (Role-Based Access Control)
  - Resource quotas & limits

## 📦 Deployment Modes

### 1. Docker Sidecar (Recommended for Development)
```yaml
# docker-compose.yml
services:
  nginx:
    image: nginx:alpine

  nxmesh-agent:
    image: nxmesh/agent:latest
    environment:
      - NXMESH_MASTER_URL=wss://master.nxmesh.io:8443
      - NXMESH_AGENT_TOKEN=${AGENT_TOKEN}
    network_mode: service:nginx  # Share network namespace
    pid: service:nginx            # Share PID namespace (for nginx reload)
```

### 2. Kubernetes Sidecar
```yaml
# deployment.yaml
spec:
  containers:
    - name: nginx
      image: nginx:alpine
    - name: nxmesh-agent
      image: nxmesh/agent:latest
      env:
        - name: NXMESH_MASTER_URL
          value: "wss://master.nxmesh.svc:8443"
```

### 3. Standalone (VM/Bare Metal)
```bash
# Install agent
curl -fsSL https://get.nxmesh.io | bash

# Configure and start
nxmesh-agent --master-url wss://master.nxmesh.io:8443 --token ${AGENT_TOKEN}
```

## 📋 Quick Start

### Prerequisites
- Docker & Docker Compose
- Rust 1.75+ (for development)
- PostgreSQL 16+

### Development Setup
```bash
# Clone and setup
git clone https://github.com/your-org/nxmesh.git
cd nxmesh
just setup

# Start development environment
just dev

# Access services
# - Web UI: http://localhost:3000
# - API: http://localhost:8080
# - Nginx: http://localhost:80
```

### Production Deployment
```bash
# Deploy master
docker run -d \
  -p 8080:8080 \
  -p 8443:8443 \
  -e DATABASE_URL=postgres://... \
  nxmesh/master:latest

# Deploy agent (on nginx host)
docker run -d \
  --network container:nginx \
  -e NXMESH_MASTER_URL=wss://master.example.com:8443 \
  -e NXMESH_AGENT_TOKEN=<token> \
  nxmesh/agent:latest
```

## 📚 Documentation

| Document | Description |
|----------|-------------|
| [Architecture](./docs/architecture.md) | System design, data flow, component interactions |
| [Features](./docs/features.md) | Detailed feature specifications |
| [Roadmap](./docs/roadmap.md) | Development phases and milestones |
| [API Reference](./docs/api.md) | REST API and gRPC specifications |
| [Deployment](./docs/deployment.md) | Production deployment guides |

## 📄 License

NxMesh is licensed under the Apache License 3.0. See [LICENSE](./LICENSE) for details.

---