# cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent architecture

> Architecture diagram of the GitHub repository cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent
- Repository: https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent

## Overview

##### Project Type and Purpose
- This is an **agentic backend microservice** (no UI) implemented as a FastAPI application that implements the AGNTCY “Terraform Code Reviewer AI Agent” protocol. It exposes both a REST interface (`/api/v1/runs`) and an AGP (Agent Gateway Protocol) interface, hosts a LangChain-based “code reviewer” chain that formats prompts and calls OpenAI/Azure LLMs, and provides a Python client for both interfaces.

##### Main Components
a. **External Systems**
- GitHub Pull‐Request (source of: diff patch + context files)
- (Optional) Terraform Static Analyzer Agent (provides `static_analyzer_output`)
- AGP Gateway (agent registry & router)
- OpenAI/Azure OpenAI LLM
b. **Infrastructure**
- Docker Container (built via `Dockerfile` / `docker-compose.yaml`)
- Kubernetes / Helm Deployment (via `deployments/helm/tf-code-reviewer-agntcy-agent`)
c. **API Layer**
- **FastAPI REST Server** (listens on port 8123)
- **AGP Server** (launched on port 46357 as a background task)
d. **Application Core**
- `main.py`: orchestrates startup, env loading, logging, FastAPI app, AGP server
- `app/api/routes/stateless_runs.py`: handles `/api/v1/runs` POST
- `app/utils/chain.py`: constructs a LangChain chain, wraps and formats prompts
- `app/utils/wrap_prompt.py`: prompt‐templating utility
- `app/core/config.py` & `logging_config.py`: environment & JSON‐logging setup
- `app/models/models.py`: request/response schemas
e. **Client Library** (`client/`)
- `rest.py`: example REST client
- `agp_client.py`: example AGP client
- `langgraph.json`: AGP client configuration

##### Relationships & Data Flows
1. **Client** (REST or AGP) → **FastAPI/AGP Server**
2. Server extracts:
- `context_files` (load `.tf` files, excluding `.tfstate`)
- `changes` (patch diff)
- `static_analyzer_output` (optional)
3. Server invokes **Chain** (`code_reviewer_chain`) → **OpenAI/Azure API**
4. LLM returns structured review comments → Server responds to client
5. **Logging**: events are emitted in JSON to stdout (or file/aggregator)
6. **Registration**: on startup, AGP server registers with AGP Gateway

##### Architectural Patterns & Principles
- **Separation of Concerns**: core logic (`chain.py`, `wrap_prompt.py`), API layer (`routes`), config/logging (`core`), models (`models`), client (`client`).
- **Background Task**: AGP server spun up post‐startup via FastAPI lifespan.
- **Dependency Injection**: FastAPI provides chain object via app state.
- **Microservice**: stateless HTTP/AGP interface, no internal database—pure compute.
- **12-Factor**: config via env vars, logs to stdout, conformance with container best practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    GitHubPR("GitHub Pull-Request"):::external
    StaticAnalyzer("Terraform Static Analyzer"):::external
    AGPGateway("AGP Gateway"):::external
    OpenAIAPI("OpenAI/Azure LLM API"):::external
    ClientREST("REST Client"):::client
    ClientAGP("AGP Client"):::client

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        DockerDef["Dockerfile"]:::infra
        ComposeDef["docker-compose.yaml"]:::infra
        K8sHelm["deployments/helm/tf-code-reviewer-agntcy-agent/"]:::infra
    end

    %% Application Container
    subgraph "FastAPI Application" 
        direction TB
        MainApp["FastAPI REST Server\n(port 8123)\n& AGP Server\n(port 46357)"]:::app
        Router["API Router"]:::app
        StatelessRuns["Stateless Runs Route\n(app/api/routes/stateless_runs.py)"]:::app
        AGPServer["AGP Server\n(background task)"]:::app
        ChainComp["code_reviewer_chain\n(app/utils/chain.py)"]:::util
        PromptUtil["wrap_prompt Utility\n(app/utils/wrap_prompt.py)"]:::util
        ConfigLoader["Config Loader\n(app/core/config.py)"]:::util
        LoggingSetup["JSON Logging Setup\n(app/core/logging_config.py)"]:::util
        ModelsComp["Pydantic Models\n(app/models/models.py)"]:::util
    end

    %% Clients to API
    ClientREST -->|HTTP POST /api/v1/runs| MainApp
    ClientAGP -->|AGP Call| MainApp

    %% Internal Routing
    MainApp -->|routes to| Router
    Router -->|calls| StatelessRuns
    MainApp -->|launches| AGPServer

    %% Chain Invocation
    StatelessRuns -->|"invokes"| ChainComp
    AGPServer -->|"invokes"| ChainComp
    ChainComp -->|uses| PromptUtil
    ChainComp -->|requests review| OpenAIAPI
    OpenAIAPI -->|returns comments| ChainComp
    ChainComp -->|responds| MainApp

    %% Optional Static Analyzer Input
    StaticAnalyzer -->|provides static_analyzer_output| MainApp
    GitHubPR -->|provides diff+context| MainApp

    %% Config & Logging usage
    ConfigLoader -->|provides env vars| MainApp
    LoggingSetup -->|emits JSON logs| MainApp

    %% AGP Registration
    AGPServer -->|registers| AGPGateway
    AGPGateway -->|routes| AGPServer

    %% Infrastructure wrapping
    DockerDef --> MainApp
    ComposeDef --> MainApp
    K8sHelm --> MainApp

    %% Click Events
    click MainApp "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/app/main.py"
    click StatelessRuns "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/app/api/routes/stateless_runs.py"
    click ChainComp "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/app/utils/chain.py"
    click PromptUtil "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/app/utils/wrap_prompt.py"
    click ConfigLoader "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/app/core/config.py"
    click LoggingSetup "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/app/core/logging_config.py"
    click ModelsComp "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/app/models/models.py"
    click ClientREST "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/client/rest.py"
    click ClientAGP "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/client/agp_client.py"
    click OpenAIAPI "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/client/langgraph.json"
    click DockerDef "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/tree/main/Dockerfile"
    click ComposeDef "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/blob/main/docker-compose.yaml"
    click K8sHelm "https://github.com/cisco-outshift-ai-agents/tf-code-reviewer-agntcy-agent/tree/main/deployments/helm/tf-code-reviewer-agntcy-agent/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px,color:#000
    classDef client fill:#fe9,stroke:#333,stroke-width:1px,color:#000
    classDef infra fill:#ccc,stroke:#333,stroke-width:1px,color:#000
    classDef app fill:#bbf,stroke:#333,stroke-width:1px,color:#000
    classDef util fill:#bfb,stroke:#333,stroke-width:1px,color:#000
```
