Architecture Overview

This document provides a high-level overview of DeepLint's architecture, focusing on the current implementation and design principles.

This is part of the Architecture documentation series:

1. Architecture Overview (current page) - High-level system architecture and design principles

2. Components - Detailed component descriptions and relationships

3. Data Flow - How data flows through the system

System Architecture

DeepLint follows a modular architecture with clear separation of concerns. The system is designed to be extensible and maintainable, with well-defined interfaces between components.

Implementation Status

The following table shows the implementation status of major components:

Component	Status	Notes
CLI	✅ Implemented	Command-line interface and argument parsing
Command System	✅ Implemented	Command registration, discovery, and execution
Context Builder	✅ Implemented	Context building orchestration
Git Integration	✅ Implemented	Git operations, diff parsing
Repository Indexing	✅ Implemented	File system scanning, dependency analysis, code structure
Context Assembly	✅ Implemented	Context assembly and token management
Configuration	✅ Implemented	Flexible configuration with cosmiconfig, validation
LLM Integration	✅ Implemented	LLM-powered analysis, OpenAI provider, prompt templates
Analysis Engine	🚧 Planned	Not yet implemented (see Roadmap)
Auto-fix Generator	🚧 Planned	Not yet implemented (see Roadmap)

For detailed descriptions of each component, see the Components documentation.

Design Principles

DeepLint's architecture is guided by the following design principles:

1. Modularity

Each component has a single responsibility and well-defined interfaces:

• CLI: Handles command-line argument parsing and execution

• Command System: Manages command registration, discovery, and execution

• Context Builder: Orchestrates the context building process

• Git Integration: Handles Git repository operations

• Repository Indexing: Analyzes repository structure and dependencies

• Context Assembly: Assembles context and manages token limits

• Configuration: Manages user configuration

2. Extensibility

The architecture is designed to be extensible:

• New commands can be added without modifying existing code

• Additional analyzers can be integrated into the context builder

• Multiple LLM providers can be supported through a common interface (planned)

3. Type Safety

DeepLint makes extensive use of TypeScript for type safety:

• Interfaces define component contracts

• Configuration is strongly typed

• Error handling is type-aware

4. Error Handling

A consistent error handling strategy is implemented:

• Custom error types for different categories of errors

• Contextual error information

• Graceful degradation when errors occur

Core Components

Command System

The command system is responsible for registering, discovering, and executing CLI commands:

• BaseCommand: Abstract base class for all commands

• CommandRegistry: Registry for command registration and discovery

• Command Discovery: Automatic discovery of commands in the commands directory

Context Builder

The context builder is responsible for gathering code context for analysis:

• Git Integration: Extracts changes from Git

• Repository Indexing: Scans the repository structure and analyzes dependencies

• Context Assembly: Assembles the context and manages token limits

Configuration System

The configuration system manages user configuration:

• Configuration Store: Persistent storage for configuration

• Configuration Schema: Type definitions for configuration

• Configuration Validation: Validation of user configuration

• Cosmiconfig Integration: Flexible configuration file discovery and loading

The configuration system uses cosmiconfig to find and load configuration from various sources:

• package.json with a "deeplint" property

• .deeplintrc files in various formats (JSON, YAML, JS)

• deeplint.config.js/cjs/mjs/ts files

• Configuration in a .config subdirectory

Build System

DeepLint uses tsup for building:

• Dual Format Output: Generates both ESM and CJS outputs for maximum compatibility

• Bundling: Bundles ESM-only dependencies like chalk for CJS compatibility

• TypeScript Compilation: Compiles TypeScript to JavaScript

• Declaration Files: Generates TypeScript declaration files

• Source Maps: Generates source maps for debugging

Architectural Decisions

Command Pattern

DeepLint uses the Command pattern for CLI commands:

• Each command is a separate class

• Commands are registered with a central registry

• Commands are discovered automatically

This approach allows for:

• Separation of concerns

• Easy addition of new commands

• Consistent command interface

Dependency Injection

DeepLint uses a simple form of dependency injection:

• Components accept dependencies in their constructors

• Default implementations are provided when dependencies are not specified

• This facilitates testing and component replacement

Configuration Management

DeepLint uses cosmiconfig for flexible configuration management:

• Configuration can be defined in multiple file formats (JS, JSON, YAML)

• Configuration can be placed in various locations (package.json, .deeplintrc, etc.)

• Configuration is defined with TypeScript interfaces for type safety

• Default values are provided for all required options

• Configuration is validated against a schema

Future Architecture

The planned architecture will extend the current design:

• LLM Integration: Abstract interface to multiple LLM providers

• Analysis Engine: Processes context to identify issues

• Auto-fix Generator: Generates fixes for detected issues

• Policy Engine: Manages custom rules and policies

For more details on how data flows through the system, see the Data Flow documentation.

Technical Constraints

DeepLint operates within the following technical constraints:

• Node.js Environment: Runs in Node.js v22+

• Module Compatibility: Supports both ESM and CJS environments

• Git Dependency: Requires Git to be installed

• Token Limits: LLMs have token limits that constrain context size

• API Key Management: Requires secure management of API keys

Developer Note: The architecture is designed to allow incremental implementation of features. The context building functionality is complete and can be used independently of the analysis capabilities.