Jet Li eb44c8ca1b feat(refactor): convert from monolithic to hybrid

2025-06-22 11:41:54 -07:00

12 KiB

Raw Permalink Blame History

DevBox Architecture Proposal: CLI + Microservices

Overview

Transform DevBox from a monolithic CLI into a lightweight client that communicates with dedicated microservices for advanced features, providing better security, maintainability, and role-based access control.

Current Problem

Security Risk: All implementation exposed in downloadable CLI
Maintenance Burden: Updates require CLI redistribution
No Access Control: Anyone with CLI has access to all features
Scalability Issues: CLI handles everything locally
Privacy Concerns: Sensitive operations happen on client machines

Proposed Solution

Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   DevBox CLI    │    │  DevBox API     │    │  Microservices  │
│   (Lightweight) │◄──►│   Gateway       │◄──►│   (Internal)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                       │                       │
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Local Setup    │    │ Authentication  │    │ Code Review     │
│  Basic Commands │    │ Authorization   │    │ CI/CD Pipeline  │
│  Docker Mgmt    │    │ Rate Limiting   │    │ AI Services     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Component Breakdown

1. DevBox CLI (Lightweight Client)

Responsibilities:

Basic local environment setup
Docker container management
Simple service start/stop/status
API communication for advanced features
Local configuration management

Features:

# Basic local operations (stay in CLI)
devbox init                    # Local environment setup
devbox start/stop/status       # Container management
devbox deinit                  # Cleanup

# Advanced features (delegate to microservices)
devbox review --component=chat # → Code Review Service
devbox package --component=chat # → CI/CD Service
devbox deploy --env=staging    # → Deployment Service
devbox ai --prompt="..."       # → AI Service

2. DevBox API Gateway

Responsibilities:

Authentication & Authorization
Rate limiting
Request routing
API versioning
Logging & monitoring
SSL termination

Authentication Flow:

1. CLI authenticates with API Gateway
2. Gateway validates credentials
3. Gateway checks permissions for requested feature
4. Gateway routes request to appropriate microservice
5. Microservice processes request and returns result

3. Microservices Architecture

A. Code Review Service

Purpose: OpenAI-powered code reviews
Endpoints: /api/v1/review/analyze, /api/v1/review/reports
Permissions: code_review:read, code_review:write
Features:
- File analysis
- Report generation
- Historical tracking
- Team collaboration

B. CI/CD Pipeline Service

Purpose: Build, test, and deployment automation
Endpoints: /api/v1/cicd/build, /api/v1/cicd/deploy, /api/v1/cicd/status
Permissions: cicd:build, cicd:deploy, cicd:read
Features:
- Docker image building
- Integration testing
- Deployment management
- Pipeline orchestration

C. AI Services

Purpose: AI-powered development assistance
Endpoints: /api/v1/ai/chat, /api/v1/ai/generate, /api/v1/ai/analyze
Permissions: ai:chat, ai:generate, ai:analyze
Features:
- Code generation
- Documentation assistance
- Bug analysis
- Performance optimization

D. Authentication Service

Purpose: User management and authentication
Endpoints: /api/v1/auth/login, /api/v1/auth/refresh, /api/v1/auth/permissions
Features:
- JWT token management
- Role-based access control
- Permission management
- Session handling

Implementation Strategy

Phase 1: CLI Refactoring

1.1 Extract Core Features

# Keep in CLI (local operations)
- Environment setup (Docker, networking)
- Container management (start/stop/status)
- Basic configuration
- Local file operations

# Move to microservices
- Code review (OpenAI integration)
- CI/CD operations
- AI-powered features
- Deployment management

1.2 Add API Communication Layer

# New CLI structure
devbox/
├── core/           # Local operations
├── api/            # API communication
├── auth/           # Authentication handling
├── config/         # Configuration management
└── commands/       # Command implementations

1.3 Implement Authentication

# Authentication flow
devbox auth login --username=user --password=pass
devbox auth status
devbox auth logout
devbox auth refresh

Phase 2: Microservices Development

2.1 API Gateway

# docker-compose.yml for development
version: '3.8'
services:
  api-gateway:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./gateway/nginx.conf:/etc/nginx/nginx.conf
      - ./gateway/ssl:/etc/nginx/ssl
    depends_on:
      - auth-service
      - review-service
      - cicd-service
      - ai-service

  auth-service:
    build: ./services/auth
    environment:
      - JWT_SECRET=your-secret-key
      - DATABASE_URL=postgresql://user:pass@db:5432/devbox

  review-service:
    build: ./services/review
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - REDIS_URL=redis://redis:6379

  cicd-service:
    build: ./services/cicd
    environment:
      - DOCKER_HOST=unix:///var/run/docker.sock
      - JENKINS_URL=${JENKINS_URL}

  ai-service:
    build: ./services/ai
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

2.2 Service Communication

# CLI API calls
curl -X POST "https://api.devbox.com/v1/review/analyze" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "component": "chat",
    "files": ["src/main.py", "src/utils.py"],
    "options": {
      "severity": ["critical", "warning"],
      "include_suggestions": true
    }
  }'

Phase 3: Role-Based Access Control

3.1 Permission System

# permissions.yaml
roles:
  developer:
    permissions:
      - code_review:read
      - cicd:build
      - ai:chat
      - ai:analyze
  
  senior_developer:
    permissions:
      - code_review:read
      - code_review:write
      - cicd:build
      - cicd:deploy
      - ai:chat
      - ai:analyze
      - ai:generate
  
  devops:
    permissions:
      - cicd:build
      - cicd:deploy
      - cicd:admin
      - deployment:read
      - deployment:write
  
  admin:
    permissions:
      - "*"  # All permissions

3.2 Feature Access Control

# CLI checks permissions before making API calls
devbox review --component=chat
# CLI checks: user has 'code_review:read' permission
# If yes: proceed with API call
# If no: show permission denied error

devbox deploy --environment=production
# CLI checks: user has 'cicd:deploy' permission
# If yes: proceed with deployment
# If no: show permission denied error

Security Benefits

1. Code Protection

Sensitive implementation hidden in microservices
CLI only contains basic setup and API communication
No exposure of AI prompts, CI/CD logic, or security configurations

2. Access Control

Role-based permissions for different features
Authentication required for advanced operations
Audit trails for all API calls
Rate limiting to prevent abuse

3. Data Privacy

Sensitive data processed on secure servers
No local storage of API keys or credentials
Encrypted communication between CLI and services
Compliance with data protection regulations

Maintenance Benefits

1. Independent Updates

Microservices can be updated independently
CLI updates only needed for basic functionality
Feature rollouts without CLI redistribution
A/B testing capabilities

2. Scalability

Services can be scaled independently
Load balancing across multiple instances
Geographic distribution for better performance
Resource optimization based on usage patterns

3. Monitoring & Analytics

Centralized logging and monitoring
Usage analytics and insights
Performance metrics for each service
Error tracking and alerting

Migration Strategy

Step 1: CLI Refactoring (Week 1-2)

# 1. Extract API communication layer
# 2. Add authentication handling
# 3. Implement permission checking
# 4. Create service stubs for testing

Step 2: Basic Microservices (Week 3-4)

# 1. Set up API Gateway
# 2. Implement Authentication Service
# 3. Create Code Review Service
# 4. Add basic CI/CD Service

Step 3: Advanced Features (Week 5-6)

# 1. Implement AI Services
# 2. Add comprehensive RBAC
# 3. Set up monitoring and logging
# 4. Performance optimization

Step 4: Production Deployment (Week 7-8)

# 1. Security hardening
# 2. Load testing
# 3. Documentation updates
# 4. User training and migration

CLI Commands After Migration

Basic Commands (Local)

devbox init                    # Local environment setup
devbox start --component=chat  # Start local containers
devbox stop --component=chat   # Stop local containers
devbox status                  # Show local status
devbox deinit                  # Cleanup local environment

Authentication Commands

devbox auth login              # Authenticate with DevBox API
devbox auth status             # Show authentication status
devbox auth logout             # Logout from DevBox API
devbox auth refresh            # Refresh authentication token

Advanced Commands (API-based)

devbox review --component=chat # AI-powered code review
devbox package --component=chat # Build and package code
devbox deploy --env=staging    # Deploy to environment
devbox ai --prompt="..."       # AI assistance
devbox pipeline --action=build # CI/CD pipeline operations

Configuration Commands

devbox config set api.url=https://api.devbox.com
devbox config set auth.token=your-token
devbox config show             # Show current configuration
devbox config reset            # Reset to defaults

Benefits Summary

For Platform Developers

Security: Sensitive code protected in microservices
Control: Role-based access to features
Analytics: Usage insights and monitoring
Scalability: Independent service scaling

For End Users

Privacy: Secure processing of sensitive data
Performance: Optimized service delivery
Reliability: Centralized monitoring and support
Features: Access to advanced AI and CI/CD capabilities

For Maintenance

Updates: Independent service updates
Monitoring: Centralized logging and alerting
Support: Better error tracking and resolution
Compliance: Audit trails and security controls

This architecture provides the perfect balance between functionality, security, and maintainability while enabling future growth and feature expansion.

12 KiB Raw Permalink Blame History