Skip to main content

Architecture Overview

Upsilon follows a modular, extensible architecture designed for composability and maintainability. This document provides a high-level overview of the system architecture and design principles.

Design Principles​

1. Composability​

Upsilon is built as a collection of loosely coupled components that can be mixed and matched:

  • Pluggable tools: Built-in and external tools through common interfaces
  • Configurable workflows: Customizable review processes
  • Multiple interfaces: CLI, API, and pre-commit integration

2. External Tool Integration​

Rather than reimplementing existing functionality, Upsilon leverages proven tools:

  • Real compilers: Python's compile(), rustc, go build
  • Established linters: mypy, ruff, eslint
  • Language servers: Future integration potential

3. Type Safety​

Built with modern Python practices:

  • mypy strict mode: Full type checking coverage
  • Pydantic models: Runtime validation and serialization
  • Generic interfaces: Type-safe plugin system

4. Testability​

Comprehensive testing strategy:

  • 59 test cases: High coverage across all components
  • Mock implementations: Testable without external dependencies
  • Integration tests: Real tool execution validation

System Architecture​

Core Components​

1. Configuration System (config.py)​

Manages all application configuration using Pydantic models:

class UpsilonConfig(BaseModel):
model: str = "claude-3-haiku-20240307"
max_tokens: int = 2000
temperature: float = 0.1
builtin_tools: Dict[str, BuiltinToolConfig] = Field(default_factory=dict)
rules: RulesConfig = Field(default_factory=RulesConfig)
prompts: PromptConfig = Field(default_factory=PromptConfig)

Key Features:

  • TOML file parsing with validation
  • Default value management
  • Type-safe configuration access
  • Hierarchical configuration structure

2. Code Reviewer (reviewer.py)​

The main orchestrator that coordinates the review process:

class CodeReviewer:
def __init__(self, config: UpsilonConfig, use_mock: bool = True):
self.config = config
self.llm_client = create_llm_client(config, use_mock=use_mock)
self._initialize_tools()

def review_file(self, file_path: Path) -> Dict[str, Any]:
# File validation and language detection
# Tool execution coordination
# LLM analysis integration
# Result aggregation

Responsibilities:

  • File type detection and validation
  • Tool initialization and registration
  • Review workflow orchestration
  • Result aggregation and formatting

3. Tool System (tools/)​

Pluggable architecture for code analysis tools:

Base Interface (tools/base.py)​

class Tool(ABC):
def __init__(self, name: str, config: Dict[str, Any]):
self.name = name
self.config = config

@abstractmethod
def analyze(self, content: str, file_path: str, language: str) -> ToolResult:
pass

@abstractmethod
def get_function_schema(self) -> Dict[str, Any]:
pass

Built-in Tools (tools/builtin.py)​

  • SpellChecker: Detects typos in comments and strings
  • SyntaxChecker: Uses language compilers for syntax validation
  • ImportAnalyzer: Checks import patterns and usage

External Tools (tools/external.py)​

  • Generic ExternalTool: Subprocess execution framework
  • Language-specific tools: mypy, ruff, rustc, go build, etc.
  • Auto-detection: Checks tool availability on system

4. LLM Integration (llm_client.py)​

Handles communication with language models:

class LLMClient(ABC):
def __init__(self, config: UpsilonConfig):
self.config = config
self.tools: Dict[str, Tool] = {}

def register_tool(self, tool: Tool) -> None:
self.tools[tool.name] = tool

@abstractmethod
def review_code(self, content: str, file_path: str,
language: str, available_tools: List[str]) -> Dict[str, Any]:
pass

Implementations:

  • MockLLMClient: Deterministic responses for testing
  • AnthropicLLMClient: Real Claude API integration with function calling

5. CLI Interface (main.py)​

Rich command-line interface using Typer and Rich:

app = typer.Typer(name="upsilon", help="AI-powered code review")

@app.command()
def review(
files: List[Path] = typer.Argument(...),
config_path: Optional[Path] = typer.Option(None),
format: OutputFormat = typer.Option(OutputFormat.text),
mock: bool = typer.Option(True),
verbose: bool = typer.Option(False),
stdin: bool = typer.Option(False)
):
# Implementation

Data Flow​

1. Initialization Flow​

CLI Command → Load Config → Initialize Reviewer → Register Tools → Ready

2. Review Flow​

File Input → Language Detection → Tool Selection → Tool Execution → 
LLM Analysis → Function Calling → Result Aggregation → Output Formatting

3. Tool Execution Flow​

Tool Registration → Availability Check → Configuration → Execution → 
Result Parsing → Normalization → Return ToolResult

Extension Points​

1. Custom Tools​

Implement the Tool interface:

class CustomTool(Tool):
def analyze(self, content: str, file_path: str, language: str) -> ToolResult:
# Custom analysis logic
pass

def get_function_schema(self) -> Dict[str, Any]:
# LLM function calling schema
pass

2. Custom LLM Clients​

Implement the LLMClient interface for other providers:

class CustomLLMClient(LLMClient):
def review_code(self, content: str, file_path: str,
language: str, available_tools: List[str]) -> Dict[str, Any]:
# Custom LLM integration
pass

3. Output Formatters​

Extend output formatting for different use cases:

class CustomFormatter:
def format_results(self, results: List[Dict[str, Any]]) -> str:
# Custom formatting logic
pass

Performance Considerations​

1. Tool Execution​

  • Parallel execution: Tools run independently
  • Caching: Results cached per file content hash
  • Timeout handling: Prevents hanging on problematic files

2. LLM Optimization​

  • Token management: Configurable limits per request
  • Batch processing: Multiple files in single request when possible
  • Model selection: Fast models for pre-commit, powerful for CI/CD

3. Memory Management​

  • Streaming: Large files processed in chunks
  • Cleanup: Temporary files automatically removed
  • Resource limits: Configurable memory and time constraints

Security Considerations​

1. External Tool Execution​

  • Sandboxing: External tools run in isolated environments
  • Input validation: All file content is validated before processing
  • Timeout enforcement: Prevents denial-of-service attacks

2. API Key Management​

  • Environment variables: API keys stored securely
  • No logging: API keys never logged or exposed
  • Validation: API key format validation

3. File Access​

  • Path validation: Prevents directory traversal attacks
  • Permission checks: Respects file system permissions
  • Temporary files: Secure temporary file creation and cleanup

Next: External Tools →