# aupc2061/codehawk architecture

> Architecture diagram of the GitHub repository aupc2061/codehawk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aupc2061/codehawk
- Repository: https://github.com/aupc2061/codehawk

## Overview

##### Project Type and Purpose
- CodeHawk is a CLI-based, multi-agent code analysis and editing system.
- It orchestrates planning, deep code understanding, and precise code modifications via natural-language interactions.
- Key use cases: AST-based code parsing, repository navigation, context-aware editing, human-in-the-loop validation.

##### File Structure and Key Components
- Top-level scripts:
- test.py – the interactive/CLI entry point
- imports.py – dependency and environment bootstrap
- setup.py & requirements.txt – packaging and dependencies
- code_agent/ directory holds the core multi-agent framework:
- main.py – initializes the LangGraph graph and CLI workflow
- routing.py – dynamic dispatch logic between agents
- core.py & config.py – global settings, TypedDict state definitions
- code_walker.py, repo_mapper.py, tree_context.py – repository and AST navigation
- tools.py – AST-based code analysis and editing utilities
- progress.py – progress monitoring, human-in-loop checkpoints
- shared_context.py & structure.py – shared state, graph node definitions

##### README for Architecture Insights
- Multi-Agent Workflow implemented via LangGraph directed graph.
- Three primary agents: Planner, Code Analysis, Code Editor.
- External dependencies: Anthropic, Google, Groq LLM APIs.
- Interactive CLI with Rich for text formatting and progress.

##### Main Components and Their Relationships
a. User Interface (CLI)
- test.py invokes main.py → Interactive session or CLI flags
- Presents model selection, workspace paths, question input
b. Planner Agent
- Entry point in the LangGraph graph
- Decomposes user request into subtasks
- Routes messages to Analysis or Editor agents via routing.py
c. Code Analysis Agent
- Uses code_walker, repo_mapper, tree_context for AST parsing and file search
- Identifies relevant files, functions, classes
- Returns structured context to Planner
d. Code Editor Agent
- Uses tools.py and structure.py to perform modifications
- Preserves formatting and encoding, runs error checks
- Passes proposed changes back for human validation
e. Human-in-the-Loop Validation
- progress.py handles interactive approval steps
- Allows accept/reject before final write-back
f. External LLM Services
- LangChain-Anthropic for Claude-3
- LangChain-Google for Gemini 2.0
- Groq for LLaMA 70B
- Agent nodes call APIs, receive completions
g. State Management
- shared_context.py holds conversation history and intermediate data
- TypedDict structures ensure consistent state across graph nodes

##### Architectural Patterns and Design Principles
- Directed Graph (LangGraph) for orchestration
- Separation of concerns: Planning, Analysis, Editing
- Plugin-style tools: code_walker, AST utilities, repo_mapper
- Human-in-the-loop gating for safety
- Typed state objects for reliability

##### Final Checklist
- Clear, descriptive labels for every component
- Boundaries showing workspace file system vs. in-memory state
- Annotation of major frameworks: LangGraph, LangChain, Rich, AST

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        User["User Input"]:::cli
        Test["test.py"]:::cli
        Main["main.py"]:::cli
    end

    %% Orchestration Layer
    subgraph "Orchestration (LangGraph)"
        direction TB
        Planner["Planner Agent"]:::agent
        Routing["routing.py"]:::state
        Analysis["Code Analysis Agent"]:::agent
        Editor["Code Editor Agent"]:::agent
        Core["core.py"]:::state
    end

    %% Tools & State
    subgraph "Tools & State"
        direction TB
        Walker["code_walker.py"]:::tools
        Mapper["repo_mapper.py"]:::tools
        TreeCtx["tree_context.py"]:::tools
        ToolsMod["tools.py"]:::tools
        Struct["structure.py"]:::tools
        Shared["shared_context.py"]:::state
        Config["config.py"]:::state
        Progress["progress.py"]:::human
    end

    %% External Services
    subgraph "External LLM Services"
        direction TB
        Anthropic["Anthropic API"]:::external
        Google["Google API"]:::external
        Groq["Groq API"]:::external
    end

    %% File System / Repository
    subgraph "File System / Repository"
        direction TB
        FS["File System"]:::fs
    end

    %% Dependency & Packaging
    subgraph "Bootstrap & Packaging"
        direction TB
        Imports["imports.py"]:::cli
        Setup["setup.py"]:::cli
        Req["requirements.txt"]:::cli
    end

    %% Connections
    User --> Test --> Main
    Main --> Planner
    Planner --> Routing
    Routing --> Analysis
    Routing --> Editor
    Analysis --> Planner
    Editor --> Planner
    Planner --> Core
    Analysis --> Walker
    Analysis --> Mapper
    Analysis --> TreeCtx
    Editor --> ToolsMod
    Editor --> Struct
    Planner --> Shared
    Planner --> Config
    Analysis --> Anthropic
    Analysis --> Google
    Analysis --> Groq
    Editor --> Anthropic
    Editor --> Google
    Editor --> Groq
    Editor --> Progress --> FS

    %% Click Events
    click Test "https://github.com/aupc2061/codehawk/blob/master/test.py"
    click Main "https://github.com/aupc2061/codehawk/blob/master/code_agent/main.py"
    click Routing "https://github.com/aupc2061/codehawk/blob/master/code_agent/routing.py"
    click Core "https://github.com/aupc2061/codehawk/blob/master/code_agent/core.py"
    click Walker "https://github.com/aupc2061/codehawk/blob/master/code_agent/code_walker.py"
    click Mapper "https://github.com/aupc2061/codehawk/blob/master/code_agent/repo_mapper.py"
    click TreeCtx "https://github.com/aupc2061/codehawk/blob/master/code_agent/tree_context.py"
    click ToolsMod "https://github.com/aupc2061/codehawk/blob/master/code_agent/tools.py"
    click Struct "https://github.com/aupc2061/codehawk/blob/master/code_agent/structure.py"
    click Progress "https://github.com/aupc2061/codehawk/blob/master/code_agent/progress.py"
    click Shared "https://github.com/aupc2061/codehawk/blob/master/code_agent/shared_context.py"
    click Config "https://github.com/aupc2061/codehawk/blob/master/code_agent/config.py"
    click Imports "https://github.com/aupc2061/codehawk/blob/master/imports.py"
    click Setup "https://github.com/aupc2061/codehawk/blob/master/setup.py"
    click Req "https://github.com/aupc2061/codehawk/blob/master/requirements.txt"

    %% Styles
    classDef agent fill:#D6EAF8,stroke:#217DBB,stroke-width:1px
    classDef tools fill:#D5F5E3,stroke:#239B56,stroke-width:1px
    classDef external fill:#FADBD8,stroke:#CB4335,stroke-width:1px
    classDef human fill:#F9E79F,stroke:#B7950B,stroke-width:1px
    classDef state fill:#FCF3CF,stroke:#B9770E,stroke-width:1px
    classDef fs fill:#E8DAEF,stroke:#8E44AD,stroke-width:1px
    classDef cli fill:#EBDEF0,stroke:#6C3483,stroke-width:1px
```
