# jaisurya2823/ai-codebase-onboarding-agent architecture

> Architecture diagram of the GitHub repository jaisurya2823/ai-codebase-onboarding-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaisurya2823/ai-codebase-onboarding-agent
- Repository: https://github.com/jaisurya2823/ai-codebase-onboarding-agent

## Overview

This CLI analyzes a supplied codebase and writes a Markdown onboarding report. Its workflow scans the repository, asks an LLM to summarize structure and risks, then synthesizes an overview and first-week tasks. The graph and shared state live in the same modules; scanner helpers are deterministic filesystem logic. The README documents Groq as the inference provider. Source excerpts show the main orchestration and scanner behavior, but not every graph-node implementation in full, so the graph preserves only relationships explicitly shown or documented.

Main entry points: [`main.py`](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/main.py) (CLI runner), [`agent/graph.py`](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py) (LangGraph workflow), [`agent/scanner.py`](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/scanner.py) (Filesystem scanner), [`agent/state.py`](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/state.py) (Shared agent state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI"]
  node_cli["CLI runner<br/>[main.py]"]
end

subgraph group_scan["Repository scanning"]
  node_scanner["Filesystem scanner<br/>[scanner.py]"]
end

subgraph group_workflow["Analysis and reporting"]
  node_workflow_graph["LangGraph workflow<br/>[graph.py]"]
  node_state["Shared agent state<br/>[state.py]"]
  node_structure["Structure analysis<br/>[graph.py]"]
  node_risk["Deep read and risks<br/>[graph.py]"]
  node_report["Report synthesis<br/>[graph.py]"]
end

node_developer(("Developer"))
node_repo["Target repository"]
node_groq{{"Groq inference"}}
node_markdown["Markdown report"]

node_developer -->|"runs"| node_cli
node_cli -->|"selects for analysis"| node_repo
node_cli -->|"builds and streams"| node_workflow_graph
node_workflow_graph -->|"scans and reads"| node_scanner
node_workflow_graph -->|"dispatches"| node_structure
node_structure -->|"then dispatches"| node_risk
node_risk -->|"then dispatches"| node_report
node_structure -->|"requests analysis"| node_groq
node_risk -->|"requests risk review"| node_groq
node_report -->|"requests synthesis"| node_groq
node_workflow_graph -->|"shares workflow data"| node_state
node_cli -->|"writes report"| node_markdown

click node_cli "https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/main.py"
click node_scanner "https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/scanner.py"
click node_workflow_graph "https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py"
click node_state "https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/state.py"
click node_structure "https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py"
click node_risk "https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py"
click node_report "https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_scanner toneAmber
class node_workflow_graph,node_state,node_structure,node_risk,node_report toneMint
class node_developer,node_repo,node_groq,node_markdown toneIndigo
```

## Components

### CLI

- [CLI runner](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/main.py): `main.py`

### Repository scanning

- [Filesystem scanner](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/scanner.py): `agent/scanner.py`

### Analysis and reporting

- [LangGraph workflow](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py): `agent/graph.py`
- [Shared agent state](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/state.py): `agent/state.py`
- [Structure analysis](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py): `agent/graph.py`
- [Deep read and risks](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py): `agent/graph.py`
- [Report synthesis](https://github.com/jaisurya2823/ai-codebase-onboarding-agent/blob/main/agent/graph.py): `agent/graph.py`

### Other components

- **Developer**
- **Target repository**
- **Groq inference**
- **Markdown report**

## Connections

- Developer → CLI runner: runs (evidence: `README.md`)
- CLI runner → Target repository: selects for analysis (evidence: `main.py`)
- CLI runner → LangGraph workflow: builds and streams (evidence: `main.py`)
- LangGraph workflow → Filesystem scanner: scans and reads (evidence: `agent/graph.py`)
- LangGraph workflow → Structure analysis: dispatches (evidence: `agent/graph.py`)
- Structure analysis → Deep read and risks: then dispatches (evidence: `agent/graph.py`)
- Deep read and risks → Report synthesis: then dispatches (evidence: `agent/graph.py`)
- Structure analysis → Groq inference: requests analysis (evidence: `agent/graph.py`)
- Deep read and risks → Groq inference: requests risk review (evidence: `agent/graph.py`)
- Report synthesis → Groq inference: requests synthesis (evidence: `agent/graph.py`)
- LangGraph workflow → Shared agent state: shares workflow data (evidence: `agent/graph.py`)
- CLI runner → Markdown report: writes report (evidence: `main.py`)
