Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (63 loc) · 2.76 KB

CLAUDE.md

File metadata and controls

87 lines (63 loc) · 2.76 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Cobalt Forward is a high-performance TCP-WebSocket forwarding service with real-time monitoring, hot reload, and plugin system capabilities. It follows clean architecture principles with domain-driven design.

Common Commands

Development

# Install dependencies
uv install

# Start development server with hot reload
python -m cobalt_forward dev --port 8000

# Start production server
python -m cobalt_forward start --config config.yaml

# Generate default configuration
python -m cobalt_forward init-config --output config.yaml

# Health check
python -m cobalt_forward health-check

Testing

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=cobalt_forward --cov-report=html

# Run specific test file
pytest tests/test_main.py -v

Code Quality

# Type checking
mypy cobalt_forward

# Code formatting
black cobalt_forward tests
isort cobalt_forward tests

# Linting
ruff cobalt_forward tests

Architecture

The project follows Clean Architecture with these main layers:

  • Application Layer (application/) - Startup orchestration and dependency injection
  • Core Layer (core/) - Business logic, domain models, and service interfaces
    • domain/ - Domain entities (commands, events, messages)
    • interfaces/ - Abstract interfaces for clients, plugins, messaging
    • services/ - Core business services (command dispatcher, event bus, message bus)
  • Infrastructure Layer (infrastructure/) - External concerns
    • clients/ - Client implementations (SSH, etc.)
    • config/ - Configuration management, backup, crypto, file watching
    • logging/ - Logging setup and management
  • Presentation Layer (presentation/) - API and external interfaces
    • api/ - FastAPI application, routers, middleware, dependencies
  • Plugins (plugins/) - Plugin system with base classes and manager

Key Design Patterns

  • Command Pattern: Commands are domain objects handled by a dispatcher
  • Event-Driven Architecture: Uses event bus and message bus for loose coupling
  • Plugin System: Dynamic loading and lifecycle management of plugins
  • Configuration Hot Reload: File watching for automatic configuration updates
  • Dependency Injection: Container-based service management

Entry Points

  • Main CLI: cobalt_forward/main:cli
  • FastAPI app: presentation/api/app.py
  • Startup orchestration: application/startup.py

Testing Structure

Tests are organized by component with comprehensive coverage including unit tests for CLI commands, API routes, core services, and integration tests. The project uses pytest with asyncio support for testing asynchronous components.