# huainguyn/adaptive-recommendation-agent architecture

> Architecture diagram of the GitHub repository huainguyn/adaptive-recommendation-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huainguyn/adaptive-recommendation-agent
- Repository: https://github.com/huainguyn/adaptive-recommendation-agent

## Overview

This repository is a standalone Adaptive Recommendation Agent demo. Its main workflow accepts a Consistency Result JSON, validates it, applies rule-based per-issue decisions, and returns a Recommendation Result JSON with a suggested next action; it does not execute that action. It also exposes a FastAPI endpoint and a terminal sample runner. The README documents coordinator integration and recommendations to request further analysis. The graph reflects the shown API, workflow, and recommender code; it does not infer calls to other agents.

Main entry points: [`agent.py`](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/agent.py) (Workflow agent), [`interface.py`](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/interface.py) (FastAPI interface), [`schema.py`](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/schema.py) (Request and result contracts), [`main.py`](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/main.py) (Sample runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry points"]
  node_api["FastAPI interface<br/>[interface.py]"]
  node_sample_runner["Sample runner<br/>[main.py]"]
end

subgraph group_workflow["Recommendation workflow"]
  node_agent["Workflow agent<br/>[agent.py]"]
  node_validation["Request validation<br/>[agent.py]"]
  node_decision["Rule-based decisions<br/>[recommender.py]"]
end

subgraph group_contracts["Data contracts"]
  node_contracts["Request and result contracts<br/>[schema.py]"]
end

node_user(("API caller"))
node_terminal_user(("Terminal user"))

node_user -->|"submits JSON"| node_api
node_api -->|"invokes"| node_agent
node_agent -->|"validates input"| node_validation
node_validation -->|"parses request"| node_contracts
node_agent -->|"runs recommendations"| node_decision
node_decision -->|"builds result"| node_contracts
node_agent -->|"returns result"| node_api
node_terminal_user -->|"runs demo"| node_sample_runner
node_sample_runner -->|"invokes"| node_agent
node_agent -->|"returns response model"| node_contracts

click node_api "https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/interface.py"
click node_sample_runner "https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/main.py"
click node_agent "https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/agent.py"
click node_validation "https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/agent.py"
click node_decision "https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/recommender.py"
click node_contracts "https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/schema.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_api,node_sample_runner,node_terminal_user toneBlue
class node_agent,node_validation,node_decision toneAmber
class node_contracts,node_user toneMint
```

## Components

### Entry points

- [FastAPI interface](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/interface.py): `interface.py`
- [Sample runner](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/main.py): `main.py`

### Recommendation workflow

- [Workflow agent](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/agent.py): `agent.py`
- [Request validation](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/agent.py): `agent.py`
- [Rule-based decisions](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/recommender.py): `recommender.py`

### Data contracts

- [Request and result contracts](https://github.com/huainguyn/adaptive-recommendation-agent/blob/main/schema.py): `schema.py`

### Other components

- **API caller**
- **Terminal user**

## Connections

- API caller → FastAPI interface: submits JSON (evidence: `README.md`)
- FastAPI interface → Workflow agent: invokes (evidence: `interface.py`)
- Workflow agent → Request validation: validates input (evidence: `agent.py`)
- Request validation → Request and result contracts: parses request (evidence: `agent.py`)
- Workflow agent → Rule-based decisions: runs recommendations (evidence: `agent.py`)
- Rule-based decisions → Request and result contracts: builds result (evidence: `recommender.py`)
- Workflow agent → FastAPI interface: returns result (evidence: `interface.py`)
- Terminal user → Sample runner: runs demo (evidence: `README.md`)
- Sample runner → Workflow agent: invokes (evidence: `main.py`)
- Workflow agent → Request and result contracts: returns response model (evidence: `agent.py`)