# shadlia/joker-reviewer architecture

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

- Interactive diagram: https://gitdiagram.com/shadlia/joker-reviewer
- Repository: https://github.com/shadlia/joker-reviewer

## Overview

##### Project Type and Purpose
- This is a Python-based autonomous agent framework (“my-first-agent”) packaged as both a CLI application and importable library.
- Core purpose: load agent configuration, build and traverse a task graph, maintain state across runs, and persist agent checkpoints and vector stores (via `.langgraph_api`).
- Key indicators:
- `main.py` and `tools.py` at project root (entry points).
- `src/agent` directory with `configuration.py`, `graph.py`, `state.py` modules.
- Persistence layer under `my-first-agent/.langgraph_api`.
- Test suites exercising configuration and graph logic.

##### File Structure Analysis
- Top-level:
- main.py – CLI entry.
- tools.py – helper scripts or library entrypoints.
- pyproject.toml – project metadata, dependencies.
- `my-first-agent/` contains the packaged agent library:
- `src/agent/` – core modules:
– configuration.py: loads and validates settings from `langgraph.json`.
– graph.py: constructs and navigates the directed graph of tasks.
– state.py: in-memory state management (current node, context, results).
- `.langgraph_api/` – persistence layer for checkpoints, operation logs, retry counters, vector embeddings.
- Tests under `tests/unit_tests` and `tests/integration_tests`.
- Build & CI:
- Makefile for common tasks.
- GitHub workflows for unit & integration tests.

##### Use Cases (per your request)
Actors:
- Developer / End-User (invokes CLI or uses library).
Primary Use Cases:
UC1: Initialize Agent
– Actor runs `python main.py --config langgraph.json`
– System loads configuration, builds task graph, initializes state.
UC2: Execute Task Graph
– Actor triggers “run” command.
– Agent traverses graph nodes in sequence or conditional branches.
– At each node: performs operation, updates state, logs to persistence.
UC3: Persist and Resume
– On exit or failure: Agent snapshots state and graph position to `.langgraph_api/store.pckl` and `.vectors`.
– Actor restarts with `--resume`, Agent reloads checkpoint, picks up from last node.

##### Main Components
- Entry Point (CLI / tools.py)
- Configuration Loader (configuration.py / langgraph.json)
- Graph Manager (graph.py)
- State Manager (state.py)
- Persistence Layer (.langgraph_api folder)
- Unit & Integration Tests (optional “test harness” component)
- Developer Actor

##### Relationships & Data Flows
- User → CLI: issues command
- CLI → Configuration Loader: reads `langgraph.json`
- Configuration Loader → Graph Manager: passes graph spec
- Graph Manager ↔ State Manager: on each node, read/write state
- Graph Manager/State Manager → Persistence Layer: checkpoint, logs, embeddings
- On resume: Persistence Layer → State Manager → Graph Manager
- Tests drive Configuration Loader and Graph Manager with mock configs.

##### Architectural Patterns & Principles
- Modular layering:
- Presentation (CLI)
- Business logic (Agent modules)
- Infrastructure (Persistence API)
- Single responsibility: each module does one thing.
- Pluggable persistence: you could swap `.langgraph_api` for a real DB by adhering to the same interface.
- Test-first design: clearly delineated unit vs. integration phases.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Use Case Overlay
    subgraph "Use Cases"
        direction TB
        Developer(("Developer")):::actor
        UC1(("UC1: Initialize Agent")):::usecase
        UC2(("UC2: Execute Task Graph")):::usecase
        UC3(("UC3: Persist and Resume")):::usecase
        Developer --> UC1
        Developer --> UC2
        Developer --> UC3
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLI_main["main.py"]:::cli
        CLI_tools["tools.py"]:::cli
    end

    %% Agent Core
    subgraph "Agent Core"
        direction TB
        Config["Configuration Loader"]:::core
        Graph["Graph Manager"]:::core
        State["State Manager"]:::core
    end

    %% Persistence Layer
    Persistence[(Persistence Layer)]:::persist

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        UT["Unit Tests"]:::test
        IT["Integration Tests"]:::test
    end

    %% CI & Build
    subgraph "CI & Build"
        direction TB
        CI_unit["unit-tests.yml"]:::infra
        CI_integ["integration-tests.yml"]:::infra
        Makefile["Makefile"]:::infra
    end

    %% Connections
    Developer --> CLI_main
    Developer --> CLI_tools
    CLI_main --> Config
    CLI_tools --> Config
    Config -->|"loads spec"| Graph
    Graph -->|"executes tasks"| State
    State -->|"checkpoint"| Persistence
    Persistence -->|"resume state"| State
    UT --> Config
    IT --> Graph
    CI_unit --> UT
    CI_integ --> IT
    Makefile --> CLI_main

    %% Click Events
    click CLI_main "https://github.com/shadlia/joker-reviewer/blob/main/main.py"
    click CLI_tools "https://github.com/shadlia/joker-reviewer/blob/main/tools.py"
    click Config "https://github.com/shadlia/joker-reviewer/blob/main/my-first-agent/src/agent/configuration.py"
    click Graph "https://github.com/shadlia/joker-reviewer/blob/main/my-first-agent/src/agent/graph.py"
    click State "https://github.com/shadlia/joker-reviewer/blob/main/my-first-agent/src/agent/state.py"
    click Persistence "https://github.com/shadlia/joker-reviewer/tree/main/my-first-agent/.langgraph_api/"
    click UT "https://github.com/shadlia/joker-reviewer/blob/main/my-first-agent/tests/unit_tests/test_configuration.py"
    click IT "https://github.com/shadlia/joker-reviewer/blob/main/my-first-agent/tests/integration_tests/test_graph.py"
    click CI_unit "https://github.com/shadlia/joker-reviewer/blob/main/my-first-agent/.github/workflows/unit-tests.yml"
    click CI_integ "https://github.com/shadlia/joker-reviewer/blob/main/my-first-agent/.github/workflows/integration-tests.yml"
    click Makefile "https://github.com/shadlia/joker-reviewer/tree/main/my-first-agent/Makefile"

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:2px
    classDef usecase fill:#efe,stroke:#2d2,stroke-width:1px,stroke-dasharray: 5 5
    classDef cli fill:#bbf,stroke:#33f,stroke-width:1px
    classDef core fill:#8cf,stroke:#06c,stroke-width:2px
    classDef persist fill:#cfc,stroke:#090,stroke-width:2px
    classDef test fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef infra fill:#ffd,stroke:#aa0,stroke-width:1px
```
