# Architecture Overview

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

{% hint style="info" %}
This is part of the Architecture documentation series:

1. **Architecture Overview** (current page) - High-level system architecture and design principles
2. [Components](https://github.com/deeplint-dev/deeplint-cli/blob/main/docs/developer/architecture/components.md) - Detailed component descriptions and relationships
3. [Data Flow](https://docs.deeplint.com/developer-guide/data-flow) - How data flows through the system
   {% endhint %}

## 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](https://docs.deeplint.com/roadmap-and-changelog/mvp-v1)) |
| Auto-fix Generator  | 🚧 Planned    | Not yet implemented (see [Roadmap](https://docs.deeplint.com/roadmap-and-changelog/mvp-v1)) |

For detailed descriptions of each component, see the [Components](https://github.com/deeplint-dev/deeplint-cli/blob/main/docs/developer/architecture/components.md) 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](https://docs.deeplint.com/developer-guide/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

{% hint style="success" %}
**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.
{% endhint %}