ARCHITECTURE.md

AutoMaintainer Architecture

AutoMaintainer is built using a modern, reactive stack designed for real-time observability and autonomous multi-agent execution.

Tech Stack

• Frontend: Next.js (React), Tailwind CSS, Framer Motion for UI/UX, and WebSockets for real-time log streaming.
• Backend: FastAPI (Python) for API handling and WebSocket management.
• Agent Orchestration: LangGraph for stateful agent pipelines.
• LLM: Llama 3 via Groq for blazing fast inference.
• Platform Integration: PyGithub for native GitHub repository interactions (Issues, Commits, PRs).

The AI Crew (LangGraph Topology)

The core logic of AutoMaintainer relies on a 5-agent engineering team that works sequentially, with a self-correcting iteration loop at the end.

graph TD
    %% Define styles
    classDef primary fill:#4f46e5,stroke:#fff,stroke-width:2px,color:#fff;
    classDef success fill:#10b981,stroke:#fff,stroke-width:2px,color:#fff;
    classDef warning fill:#f59e0b,stroke:#fff,stroke-width:2px,color:#fff;
    classDef danger fill:#ef4444,stroke:#fff,stroke-width:2px,color:#fff;
    classDef secondary fill:#6b7280,stroke:#fff,stroke-width:2px,color:#fff;

    A([Start Pipeline]) --> B[Architect Node]
    
    B --> C[Visionary Node]
    C --> D[PM / Reviewer Node]
    
    D -->|Approved| E[Implementer Node]
    D -->|Rejected| F([End Pipeline])
    
    E --> G[Maintainer Node]
    
    G -->|LGTM| H([Merge & End])
    G -->|Bug Detected| I{Iteration < 3?}
    
    I -->|Yes| E
    I -->|No| F

    class A,F,H secondary;
    class B,C,D,E,G primary;

Agent Roles

1. Architect (Principal Engineer): Scans the target repository's file tree and README. Assesses the tech stack and project state, then generates a strict architectural directive.
2. Visionary (Brainstormer): Reads the directive and ideates a single, innovative feature. It opens a native GitHub Issue detailing the proposed feature.
3. Reviewer (Product Manager): Evaluates the feature against the original directive. If approved, it comments on the GitHub Issue. If rejected, it closes the Issue and stops the pipeline.
4. Implementer (Developer): Writes the actual Python code to build the feature. It pushes the code to a new branch and opens a Pull Request linked to the Issue. If returning from a rejection loop, it reads the feedback and pushes a new commit to the existing branch.
5. Maintainer (Senior Engineer): Reviews the code in the PR. If it spots a flaw, it leaves a comment and routes the pipeline back to the Implementer (up to 3 times). If the code is solid, it outputs LGTM and automatically merges the Pull Request!