ROSAN: Resilient Orchestration & Self-Healing Agentic Network

A fault-tolerant multi-agent orchestration framework built with LangGraph, featuring autonomous recovery mechanisms, hierarchical supervision, and real-time monitoring capabilities.

🎯 What is ROSAN?

ROSAN is a production-ready framework for creating resilient multi-agent systems that can:

• Autonomous Recovery: Automatically detect and recover from agent failures
• Hierarchical Supervision: Supervisor-worker architecture with intelligent task distribution
• Real-time Monitoring: Live dashboard showing system health, agent status, and workflow progress
• Fault Tolerance: Byzantine fault-tolerant consensus mechanisms
• Scalable Orchestration: Dynamic agent scaling and workflow management

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    ROSAN Architecture                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Frontend      │  │   Backend API   │  │  Data Layer     │ │
│  │   Dashboard     │  │   (Port 3001)   │  │                 │ │
│  │   (Port 5173)   │  │                 │  │  PostgreSQL     │ │
│  │                 │  │ ┌─────────────┐ │  │  (Port 5432)    │ │
│  │  • React UI     │  │ │ LangGraph   │ │  │                 │ │
│  │  • Real-time    │  │ │ Orchestration│ │  │  Redis         │ │
│  │  • Monitoring   │  │ │ Engine       │ │  │  (Port 6379)    │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│           │                      │                      │      │
│           └──────────────────────┼──────────────────────┘      │
│                                  │                             │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Agent Layer                              │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │ │
│  │  │ Supervisor  │  │ Inspector   │  │ Recovery Subgraphs  │  │ │
│  │  │ Agents      │  │ Agents      │  │                     │  │ │
│  │  │             │  │             │  │ • Failure Detection │  │ │
│  │  │ • Task Mgmt │  │ • Validation │  │ • Auto-Recovery     │  │ │
│  │  │ • Monitoring│  │ • Auditing   │  │ • Rollback          │  │ │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘  │ │
│           │                      │                      │      │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                   Worker Agents                             │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │ │
│  │  │ Worker 1    │  │ Worker 2    │  │     Worker N        │  │ │
│  │  │             │  │             │  │                     │  │ │
│  │  │ • Execute   │  │ • Execute   │  │ • Execute Tasks     │  │ │
│  │  │ • Report    │  │ • Report    │  │ • Report Status     │  │ │
│  │  │ • Challenge │  │ • Challenge │  │ • Challenge Invalid │  │ │
│  │  └─────────────┘  └─────────────┘  └─────────────────────┘  │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

System Requirements:

• Node.js: >= 18.0.0
• npm: >= 8.0.0
• Docker: >= 20.10.0
• Docker Compose: >= 2.0.0
• Operating System: Linux, macOS, or Windows with WSL2

Required Services:

• PostgreSQL 14+ (automatically provisioned)
• Redis 7+ (automatically provisioned)
• LangGraph API key (required for orchestration)

One-Command Setup

# Clone the repository
git clone <repository-url>
cd ROSAN

# Set up everything automatically
chmod +x scripts/setup-docker.sh
./scripts/setup-docker.sh

# Start the application
npm start

What this does:

• ✅ Creates PostgreSQL and Redis containers
• ✅ Configures environment variables
• ✅ Builds Docker images
• ✅ Starts all services
• ✅ Initializes database schema
• ✅ Validates setup

Manual Setup

If you prefer manual setup or need custom configuration:

# 1. Install dependencies
npm install

# 2. Set up environment
cp .env.example .env
# Edit .env with your configuration

# 3. Start database services
docker-compose -f docker-compose.dev.yml up -d postgres redis

# 4. Initialize database
npm run db:migrate

# 5. Start application
npm run dev:backend
npm run dev:frontend

📋 Configuration

Environment Variables

Create a .env file with the following configuration:

# Server Configuration
NODE_ENV=development
PORT=3001
HOST=localhost

# Database Configuration
DATABASE_URL=postgresql://rosan_user:password@localhost:5432/rosan_db
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=rosan_db
DATABASE_USER=rosan_user
DATABASE_PASSWORD=your_secure_password
DATABASE_SSL=false

# Redis Configuration
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0

# LangGraph Configuration (REQUIRED)
LANGGRAPH_API_KEY=your_langgraph_api_key
LANGGRAPH_PROJECT_ID=rosan_dev
LANGGRAPH_ENVIRONMENT=development

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_change_in_production
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d

# Agent Configuration
AGENT_TIMEOUT=30000
AGENT_MAX_RETRIES=3
AGENT_RETRY_DELAY=1000
MAX_CONCURRENT_AGENTS=10

# WebSocket Configuration
WS_PORT=3002
WS_PATH=/socket.io
WS_CORS_ORIGIN=http://localhost:3000

# Logging Configuration
LOG_LEVEL=info
LOG_FILE_PATH=./logs/rosan.log
LOG_MAX_SIZE=20m
LOG_MAX_FILES=14d

# Security Configuration
CORS_ORIGIN=http://localhost:3000
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
HELMET_ENABLED=true

LangGraph API Key

Required for ROSAN functionality:

1. Visit LangGraph
2. Create an account and obtain API key
3. Set LANGGRAPH_API_KEY in your environment
4. Test connection: curl -H "Authorization: Bearer YOUR_KEY" https://api.langgraph.com

🖥️ Usage

Starting the Application

Development Mode:

# Start all services
npm start

# Or start components individually
npm run dev:backend    # Backend API on port 3001
npm run dev:frontend   # Frontend dashboard on port 5173
npm run dashboard      # Alternative dashboard on port 3000

Production Mode:

# Build for production
npm run build

# Start production server
npm run start:prod

Accessing Services

Service	URL	Description
Backend API	http://localhost:3001	REST API and WebSocket server
Frontend Dashboard	http://localhost:5173	Main monitoring dashboard
Alternative Dashboard	http://localhost:3000	Alternative dashboard interface
Health Check	http://localhost:3001/health	System health status
API Status	http://localhost:3001/api/v1/status	Detailed system status

Basic API Usage

# Check system health
curl http://localhost:3001/health

# Get detailed system status
curl http://localhost:3001/api/v1/status

# Create a workflow (when agents are running)
curl -X POST http://localhost:3001/api/v1/workflows/create \
  -H "Content-Type: application/json" \
  -d '{"name":"my-workflow","description":"Test workflow"}'

Dashboard Features

The ROSAN dashboard provides:

• System Overview: Real-time system health and metrics
• Agent Network: Visual representation of agent topology
• Workflow Monitoring: Active workflows and their progress
• Recovery Operations: Failure detection and recovery status
• Performance Metrics: Resource usage and response times
• Alert Center: System alerts and notifications

🧪 Testing

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit        # Unit tests
npm run test:integration # Integration tests
npm run test:e2e        # End-to-end tests
npm run test:coverage   # Tests with coverage report

Test Coverage

ROSAN includes comprehensive test coverage for:

• ✅ Backend API: All endpoints and business logic
• ✅ Database Layer: Schema validation and queries
• ✅ Agent Framework: Supervisor-worker interactions
• ✅ Recovery Systems: Failure detection and recovery
• ✅ WebSocket Communication: Real-time data flow
• ✅ Security: Authentication and authorization

Validation Commands

# Validate entire setup
npm run validate

# Check service health
npm run health-check

# Test database connectivity
npm run test:db

# Test Redis connectivity
npm run test:redis

🔧 Development

Project Structure

ROSAN/
├── src/
│   ├── agents/                 # Agent framework
│   │   ├── supervisor/         # Supervisor agents
│   │   ├── workers/           # Worker agents
│   │   ├── inspector/         # Inspector agents
│   │   └── communication/     # Agent communication
│   ├── dashboard/             # Frontend React dashboard
│   │   ├── components/        # React components
│   │   ├── pages/            # Dashboard pages
│   │   ├── hooks/            # Custom React hooks
│   │   └── store/            # Redux state management
│   ├── database/             # Database models and schemas
│   ├── langgraph/            # LangGraph orchestration
│   ├── security/             # Security and monitoring
│   ├── server/               # Express.js API server
│   └── utils/                # Utility functions
├── tests/                    # Test files
├── scripts/                  # Setup and utility scripts
├── docs/                     # Documentation
├── config/                   # Configuration files
└── docker-compose.dev.yml    # Docker configuration

Adding New Agents

// src/agents/your-agent/YourAgent.ts
import { ResilientAgent } from '../base/resilient-agent';

export class YourAgent extends ResilientAgent {
  constructor(config: AgentConfig) {
    super(config);
  }

  async execute(task: Task): Promise<TaskResult> {
    // Implement your agent logic here
    try {
      const result = await this.processTask(task);

      // Inspector validation
      const isValid = await this.inspector.validate(result);
      if (!isValid) {
        throw new Error('Task validation failed');
      }

      return result;
    } catch (error) {
      // Automatic recovery
      return this.supervisor.handleFailure(task, error);
    }
  }
}

Custom Workflows

// src/langgraph/workflows/your-workflow.ts
import { StateGraph } from '@langchain/langgraph';

export const createYourWorkflow = () => {
  const workflow = new StateGraph(YourStateSchema);

  workflow
    .addNode('validate', validateInput)
    .addNode('process', processData)
    .addNode('recover', handleFailure)
    .addEdge('validate', 'process')
    .addEdge('process', END)
    .addConditionalEdges('process', shouldRecover, {
      recover: 'recover',
      end: END
    });

  return workflow.compile();
};

🐳 Docker Deployment

Using Docker Compose

# Start all services
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Stop services
docker-compose -f docker-compose.dev.yml down

Production Docker

# Build production images
docker build -f Dockerfile.backend -t rosan-backend .
docker build -f Dockerfile.frontend -t rosan-frontend .

# Run with external databases
docker run -d \
  --name rosan-backend \
  -p 3001:3001 \
  --env-file .env \
  rosan-backend

Service Ports

Service	Internal Port	External Port	Description
Backend API	3001	3001	Main API server
Frontend	5173	5173	Development dashboard
PostgreSQL	5432	5432	Primary database
Redis	6379	6379	Cache and session store
Prometheus	9090	9090	Metrics collection
Grafana	3000	3002	Monitoring dashboard

🔍 Troubleshooting

Common Issues

1. Port Conflicts

# Check what's using ports
netstat -tulpn | grep :3001
lsof -i :5432

# Kill conflicting processes
sudo kill -9 <PID>

2. Database Connection Issues

# Check PostgreSQL container
docker ps | grep postgres
docker logs rosan-postgres

# Test connection
PGPASSWORD=your_password psql -h localhost -p 5432 -U rosan_user -d rosan_db

3. Redis Connection Issues

# Check Redis container
docker ps | grep redis
docker logs rosan-redis

# Test connection
redis-cli -h localhost -p 6379 -a your_password ping

4. Frontend Build Errors

# Clear node modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check TypeScript compilation
npm run type-check

5. API Not Responding

# Check backend logs
docker logs rosan-backend

# Verify environment variables
cat .env | grep -E "(PORT|DATABASE|REDIS)"

# Test health endpoint
curl -v http://localhost:3001/health

Debug Mode

Enable detailed logging:

# Set debug environment
export DEBUG=rosan:*
export LOG_LEVEL=debug

# Start with verbose logging
npm run dev:backend -- --verbose

Performance Issues

# Monitor resource usage
docker stats

# Check database performance
PGPASSWORD=your_password psql -h localhost -p 5432 -U rosan_user -d rosan_db -c "
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY total_time DESC LIMIT 10;"

# Profile Node.js application
npm run profile

📊 Performance Characteristics

Benchmarks

Metric	Value	Description
API Response Time	< 50ms	Average API endpoint response
WebSocket Latency	< 10ms	Real-time communication latency
Database Query Time	< 100ms	Average PostgreSQL query
Cache Hit Rate	> 95%	Redis cache performance
Memory Usage	< 512MB	Typical application memory
CPU Usage	< 10%	Normal operation CPU usage

Scalability

• Horizontal Scaling: Supports multiple backend instances
• Database Scaling: PostgreSQL read replicas supported
• Cache Scaling: Redis clustering supported
• Agent Scaling: Dynamic agent creation and termination

Limitations

• Single Region: Designed for single-region deployment
• Database: PostgreSQL connection pooling required for high load
• Memory: Agent state stored in memory (persistence available)
• API Rate Limits: Configurable rate limiting for API endpoints

🔒 Security

Authentication

• JWT Tokens: Secure token-based authentication
• API Keys: LangGraph API key authentication
• Database Security: Password-based authentication with SSL

Network Security

• CORS: Configurable cross-origin resource sharing
• Rate Limiting: Configurable request rate limits
• HTTPS: SSL/TLS encryption in production
• Firewall: Configurable network access rules

Data Protection

• Encryption: Data encryption in transit and at rest
• Audit Logging: Comprehensive audit trail
• Backup: Automated database backups
• Compliance: GDPR and SOC 2 compliance features

📚 API Reference

Core Endpoints

Health Check

GET /health

Returns system health status.

System Status

GET /api/v1/status

Returns detailed system status including agents and workflows.

Create Workflow

POST /api/v1/workflows/create
Content-Type: application/json

{
  "name": "workflow-name",
  "description": "Workflow description",
  "config": {}
}

WebSocket Events

Agent Status Updates

socket.on('agent:status', (data) => {
  console.log('Agent status:', data);
});

Workflow Progress

socket.on('workflow:progress', (data) => {
  console.log('Workflow progress:', data);
});

System Alerts

socket.on('system:alert', (alert) => {
  console.log('System alert:', alert);
});

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the test suite: npm test
5. Ensure all tests pass: npm run test:coverage
6. Submit a pull request

Code Style

• TypeScript: Strict TypeScript with type definitions
• ESLint: Follow configured linting rules
• Prettier: Use Prettier for code formatting
• Tests: Maintain >80% test coverage

Submitting Issues

Include the following information:

1. ROSAN Version: npm run version
2. Node.js Version: node --version
3. Operating System: uname -a
4. Error Message: Full error stack trace
5. Steps to Reproduce: Detailed reproduction steps
6. Expected Behavior: What should happen
7. Actual Behavior: What actually happens

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation

• API Documentation: /docs/api/
• Agent Development: /docs/agents/
• Deployment Guide: /docs/deployment/
• Troubleshooting: /docs/troubleshooting/

Community

• GitHub Issues: Report bugs and request features
• Discussions: Community discussions and Q&A
• Wiki: Community-maintained documentation

Professional Support

For enterprise support and custom development, contact the ROSAN team.

---

ROSAN: Building the future of resilient multi-agent systems through autonomous orchestration and self-healing capabilities.