# NexusCLI Backend Documentation

**Version**: 0.1.0
**Created**: 2025-11-17
**Status**: Design Phase

---

## 📚 Documentation Index

This directory contains the **official design documentation** for NexusCLI backend, based on analysis of the NexusChat wrapper architecture.

### Core Documents

| Document | Purpose | Audience |
|----------|---------|----------|
| **⭐ [Design Principles](./DESIGN_PRINCIPLES.md)** | **Three Pillars**: Lightweight, Portable, ChatGPT UI | **Everyone - Start here!** |
| **[Database Schema](./DATABASE_SCHEMA.md)** | SQLite schema for chat/sessions (Linux + Termux friendly) | Backend developers, DB admins |
| **[API & Wrapper Contract](./API_WRAPPER_CONTRACT.md)** | Complete API specification for Control Plane and node wrappers | Backend developers, API consumers |
| **[Architecture Overview](./ARCHITECTURE.md)** | High-level system architecture and component design | System architects, DevOps |
| **[Pipeline Integration](./PIPELINE_INTEGRATION.md)** | How the 5-phase pipeline works (Analysis → Deploy) | Product managers, full-stack developers |
| **[NexusChat Analysis](./NEXUSCHAT_ANALYSIS.md)** | Detailed analysis of reference implementation | Backend developers, researchers |

---

## 🎯 Quick Start

### For Everyone

**Start with**: [Design Principles](./DESIGN_PRINCIPLES.md) - Understand the three pillars (Lightweight, Portable, ChatGPT UI)

### For Backend Developers

1. Read [Architecture Overview](./ARCHITECTURE.md) to understand the system design
2. Review [API Contract](./API_WRAPPER_CONTRACT.md) for endpoint specifications
3. Study [Pipeline Integration](./PIPELINE_INTEGRATION.md) for workflow logic
4. Check [NexusChat Analysis](./NEXUSCHAT_ANALYSIS.md) for reference implementation details

### For Frontend Developers

1. Focus on **API Contract** sections:
   - Control Plane API endpoints
   - SSE event streaming format
   - Data structures (Node, Job, Event)

### For DevOps Engineers

1. Read **Architecture** for deployment strategy
2. Check **Pipeline Integration** for monitoring metrics
3. See **API Contract** for health check endpoints

---

## 🏗️ Architecture Summary

**NexusCLI** = Distributed control plane for CLI orchestration

```
┌───────────────┐
│   Frontend    │  ← React dashboard
└───────┬───────┘
        │ REST API + SSE
        ↓
┌───────────────┐
│ Control Plane │  ← Express.js (this codebase)
└───────┬───────┘
        │ HTTP
        ↓
┌───────────────┐
│ nexus-wrapper │  ← Node agent (separate repo)
└───────┬───────┘
        │ PTY
        ↓
┌───────────────┐
│   CLI Tools   │  ← bash, git, docker, etc.
└───────────────┘
```

**Inspired by**: NexusChat's claude-code-server wrapper architecture

---

## 🔄 5-Phase Pipeline

```
Analysis → Coordination → Execution → Test → Deploy
```

Each job follows this pipeline:

1. **Analysis**: Validate command, check feasibility
2. **Coordination**: Select node, queue job
3. **Execution**: Run command, stream output
4. **Test**: Verify results, assert expectations
5. **Deploy**: Apply changes, trigger follow-ups

See [Pipeline Integration](./PIPELINE_INTEGRATION.md) for details.

---

## 📊 Data Structures

### Node
```json
{
  "nodeId": "node-001",
  "hostname": "server-prod-1",
  "status": "online",
  "capabilities": {
    "tools": ["bash", "git", "docker"]
  }
}
```

### Job
```json
{
  "jobId": "job-123",
  "nodeId": "node-001",
  "status": "completed",
  "tool": "bash",
  "command": "ls -la",
  "result": {
    "exitCode": 0,
    "stdout": "...",
    "duration": 123
  }
}
```

### Event (SSE)
```json
{
  "type": "status",
  "category": "tool",
  "message": "Bash: ls -la",
  "icon": "🔧"
}
```

---

## 🔗 Key APIs

### Control Plane

```
POST   /api/v1/nodes/register      # Register node
GET    /api/v1/nodes               # List nodes
POST   /api/v1/jobs                # Create job
GET    /api/v1/jobs/:id/stream     # SSE stream
GET    /api/v1/jobs/:id            # Get result
DELETE /api/v1/jobs/:id            # Cancel job
```

### Node Wrapper

```
GET    /api/v1/health              # Health check
GET    /api/v1/capabilities        # List tools
POST   /api/v1/jobs                # Execute job
GET    /api/v1/jobs/:id/stream     # SSE stream
```

---

## 🧪 Implementation Status

| Component | Status | Priority |
|-----------|--------|----------|
| Control Plane API | 📝 Designed | High |
| Node Registry | 📝 Designed | High |
| Job Manager | 📝 Designed | High |
| SSE Streaming | 📝 Designed | High |
| nexus-wrapper | 📝 Designed | Medium |
| Output Parser | 📝 Designed | Medium |
| Frontend Dashboard | ✅ Bootstrap | Medium |
| Pipeline Templates | 📝 Designed | Low |
| WellaNet Integration | 🔮 Future | Low |

**Legend**: ✅ Done | 🔄 In Progress | 📝 Designed | 🔮 Future

---

## 📖 Design Philosophy

### Learned from NexusChat

1. **PTY over Subprocess**: Use `node-pty` for real TTY simulation
2. **2-Layer Persistence**: RAM cache + disk storage for crash recovery
3. **SSE for Streaming**: Server-Sent Events for real-time updates
4. **Output Parser State Machine**: Regex-based parsing with state tracking
5. **Graceful Shutdown**: Handle SIGTERM, save in-flight jobs

### Generalized for NexusCLI

- **Wrapper abstraction**: Generic interface for any CLI tool
- **Multi-node orchestration**: Control plane coordinates multiple wrappers
- **Pipeline thinking**: Every job follows Analysis → Deploy workflow
- **Event-driven**: All updates flow through SSE event streams

---

## 🔐 Security Considerations

### Authentication
- JWT tokens for API clients
- Bearer tokens for node wrappers
- Rate limiting per user/node

### Authorization
- RBAC for job execution
- Tool restrictions per node
- Command whitelisting/blacklisting

### Isolation
- Isolated working directories
- Resource limits (CPU, memory, timeout)
- No access to wrapper process environment

---

## 📈 Performance Targets

| Metric | Target |
|--------|--------|
| Job submission latency | < 100ms |
| SSE event latency | < 50ms |
| Concurrent jobs (per node) | 5-10 |
| Control plane throughput | 100 jobs/sec |
| Node wrapper memory | < 100MB |

---

## 🚀 Next Steps

### Immediate (Phase 1)

1. Implement Control Plane API endpoints
2. Create nexus-wrapper reference implementation
3. Adapt OutputParser for generic CLI tools
4. Set up systemd services

### Short-term (Phase 2)

1. Add WebSocket support (alternative to SSE)
2. Implement job scheduling (cron-like)
3. Create pipeline templates
4. Add approval workflows

### Long-term (Phase 3)

1. WellaNet integration (compute marketplace)
2. AI-assisted command validation
3. Blockchain-based node registry
4. Multi-cloud orchestration

---

## 📞 Contact & Contribution

**Project Lead**: Davide A. Guglielmi
**Email**: dev@mmmbuto.com
**Repository**: `/var/www/cli.wellanet.dev/`

**Based on**:
- NexusChat wrapper architecture (`/var/www/chat.mmmbuto.com/servers/claude-code-server/`)
- Production experience with 100+ daily requests

---

_All documentation generated with [Claude Code](https://claude.com/claude-code) (Sonnet 4.5)_
