AutoMaintainer: Phases 1-4 Architectural Summary

[purvanshjoshi]

AutoMaintainer: Phases 1-4 Architectural Summary

This document provides a highly descriptive overview of the first four implementation phases for the AutoMaintainer ecosystem. It outlines the specific features, the GitHub issues tracked, the pull requests merged, and the visual flow of the resulting architecture.

---

Phase 1: Native AST Codebase Analyzer via Tree-Sitter

Original Issue: #18 (Migrated to Discussion #31)
Pull Request: #22

Description:
The goal of Phase 1 was to transition the autonomous agents from blind grepping to deep syntactic understanding. We implemented the CodebaseMapper in the Python backend, which leverages the tree-sitter library to parse raw source code into an Abstract Syntax Tree (AST). This allowed the system to extract classes, functions, and docstrings structurally, creating a semantic map of any cloned repository without relying on static text searches.

Phase 2: Expose File System Tree API for Web IDE

Original Issue: #19 (Migrated to Discussion #32)
Pull Request: #23

Description:
To support a rich visual frontend, we needed to expose the local filesystem securely. Phase 2 involved building two robust REST endpoints (/repo/{repo_name}/tree and /repo/{repo_name}/file) into the FastAPI backend. These endpoints recursively traverse the local repository clone, validate directories, and serve raw code content back to the frontend, acting as the data backbone for the incoming Web IDE.

Phase 3: Build Split-Pane Web IDE Interface

Original Issue: #20 (Migrated to Discussion #33)
Pull Request: #24

Description:
Phase 3 focused entirely on the user experience. We transformed the basic Next.js React dashboard into a professional, VS Code-like split-pane Web IDE. It features a left-side FileExplorer component that renders a collapsible directory tree by calling the Phase 2 APIs, a central main viewing pane equipped with syntax-highlighted code visualization, and a real-time agent execution log panel that monitors live WebSockets.

Phase 4: Integrate Native AST Mapping into LangGraph Agents

Original Issue: #21 (Migrated to Discussion #34)
Pull Request: #25

Description:
The final integration phase connected the AST analyzer directly into the LangGraph state machine. We wired the architect_node to execute the CodebaseMapper, injecting up to 15,000 characters of serialized AST context directly into the Groq LLM prompts. Furthermore, we resolved asynchronous blocking bottlenecks by migrating the Git cloning and GitNexus indexing processes to asyncio subprocesses, ensuring the FastAPI WebSockets remained highly responsive during large repository evaluations.

---

Visual Architecture Representation

graph TD
    %% Styling
    classDef frontend fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#fff;
    classDef backend fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff;
    classDef agents fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff;
    classDef parser fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#fff;

    %% Nodes
    User([Developer User])
    
    subgraph "Phase 3: Web IDE Frontend"
        Dashboard[Next.js Dashboard]:::frontend
        FileExplorer[File Explorer Pane]:::frontend
        Logs[Live Agent Logs]:::frontend
    end
    
    subgraph "Phase 2: FastAPI Backend"
        API_Tree[GET /repo/tree]:::backend
        API_File[GET /repo/file]:::backend
        WS[WebSocket Manager]:::backend
    end
    
    subgraph "Phase 4: LangGraph Engine"
        Architect[Architect Node]:::agents
        State[Agent State Machine]:::agents
    end
    
    subgraph "Phase 1: Codebase Intelligence"
        CodebaseMapper[AST CodebaseMapper]:::parser
        TreeSitter[(Tree-Sitter Index)]:::parser
    end

    %% Connections
    User -->|Interacts| Dashboard
    Dashboard -->|Renders| FileExplorer
    Dashboard -->|Listens| Logs
    
    FileExplorer -->|Requests Directory| API_Tree
    FileExplorer -->|Requests Content| API_File
    
    API_Tree --> State
    API_File --> State
    
    Dashboard -->|Triggers Target Issue| WS
    WS <-->|Streams Status Updates| Logs
    WS --> State
    
    State --> Architect
    Architect -->|Triggers Async Execution| CodebaseMapper
    CodebaseMapper -->|Parses Syntax| TreeSitter
    TreeSitter -->|Returns Serialized Structure| Architect
    
    Architect -->|Passes Context| LLM((Groq LLM))

Loading

Tip

The synchronous boundaries in Phase 4 were entirely refactored to asyncio to ensure the WebSocket Manager is never starved of execution threads while the AST CodebaseMapper is processing massive repositories.

[purvanshjoshi]

@archittmittal what are your review on this