# jrgkog/foai-project-multiagent architecture

> Architecture diagram of the GitHub repository jrgkog/foai-project-multiagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jrgkog/foai-project-multiagent
- Repository: https://github.com/jrgkog/foai-project-multiagent

## Overview

This is a CLI container-resource advisor demo. A user selects normal, CPU-stress, or memory-stress scenarios; the CLI starts workload processes, samples their metrics, runs each service through a four-agent LangGraph analysis, and displays scaling advice. The agents share validated state and use Gemini with deterministic fallbacks. The README is empty; the workflow and links below are grounded in the shown excerpts and SOURCE INDEX. Some CLI collection and shutdown details are omitted from the excerpt, so their internal sequence is not expanded.

Main entry points: [`main.py`](https://github.com/jrgkog/foai-project-multiagent/blob/main/main.py) (Scenario runner), [`agents/llm_factory.py`](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/llm_factory.py) (LLM factory), [`agents/state.py`](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/state.py) (Typed agent state), [`agents/monitoring_agent.py`](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/monitoring_agent.py) (Monitoring agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI workflow"]
  node_main["Scenario runner<br/>[main.py]"]
  node_pipeline["Agent pipeline<br/>[pipeline.py]"]
end

subgraph group_workloads["Workload and metrics"]
  node_services["Load processes<br/>[services.py]"]
  node_metrics["Process metrics<br/>[process_metrics.py]"]
end

subgraph group_analysis["Advisor agents"]
  node_monitor["Monitoring agent"]
  node_bottleneck["Bottleneck analysis"]
  node_scaling["Scaling decision<br/>[scaling_agent.py]"]
  node_recommendation["Recommendation"]
end

subgraph group_shared["Shared intelligence"]
  node_state["Typed agent state<br/>[state.py]"]
  node_llm["LLM factory<br/>[llm_factory.py]"]
end

node_user(("CLI user"))
node_gemini["Gemini API"]
node_psutil["psutil process API"]

node_user -->|"selects scenario"| node_main
node_main -->|"spawns workloads"| node_services
node_main -->|"collects metrics"| node_metrics
node_metrics -->|"samples process"| node_psutil
node_main -->|"runs analysis"| node_pipeline
node_pipeline -->|"dispatches first"| node_monitor
node_monitor -->|"passes state"| node_bottleneck
node_bottleneck -->|"passes state"| node_scaling
node_scaling -->|"passes state"| node_recommendation
node_monitor -->|"validates metrics"| node_state
node_bottleneck -->|"models results"| node_state
node_scaling -->|"models decision"| node_state
node_recommendation -->|"models result"| node_state
node_pipeline -->|"types graph state"| node_state
node_monitor -->|"requests summary"| node_llm
node_bottleneck -->|"requests diagnosis"| node_llm
node_scaling -->|"requests decision"| node_llm
node_recommendation -->|"requests narrative"| node_llm
node_llm -->|"generates content"| node_gemini
node_main -->|"displays report"| node_user

click node_main "https://github.com/jrgkog/foai-project-multiagent/blob/main/main.py"
click node_services "https://github.com/jrgkog/foai-project-multiagent/blob/main/services.py"
click node_metrics "https://github.com/jrgkog/foai-project-multiagent/blob/main/tools/process_metrics.py"
click node_pipeline "https://github.com/jrgkog/foai-project-multiagent/blob/main/pipeline.py"
click node_monitor "https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/monitoring_agent.py"
click node_bottleneck "https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/bottleneck_agent.py"
click node_scaling "https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/scaling_agent.py"
click node_recommendation "https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/recommendation_agent.py"
click node_state "https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/state.py"
click node_llm "https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/llm_factory.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_main,node_pipeline,node_user toneBlue
class node_services,node_metrics toneAmber
class node_monitor,node_bottleneck,node_scaling,node_recommendation,node_gemini,node_psutil toneMint
class node_state,node_llm toneRose
```

## Components

### CLI workflow

- [Scenario runner](https://github.com/jrgkog/foai-project-multiagent/blob/main/main.py): `main.py`
- [Agent pipeline](https://github.com/jrgkog/foai-project-multiagent/blob/main/pipeline.py): `pipeline.py`

### Workload and metrics

- [Load processes](https://github.com/jrgkog/foai-project-multiagent/blob/main/services.py): `services.py`
- [Process metrics](https://github.com/jrgkog/foai-project-multiagent/blob/main/tools/process_metrics.py): `tools/process_metrics.py`

### Advisor agents

- [Monitoring agent](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/monitoring_agent.py): `agents/monitoring_agent.py`
- [Bottleneck analysis](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/bottleneck_agent.py): `agents/bottleneck_agent.py`
- [Scaling decision](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/scaling_agent.py): `agents/scaling_agent.py`
- [Recommendation](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/recommendation_agent.py): `agents/recommendation_agent.py`

### Shared intelligence

- [Typed agent state](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/state.py): `agents/state.py`
- [LLM factory](https://github.com/jrgkog/foai-project-multiagent/blob/main/agents/llm_factory.py): `agents/llm_factory.py`

### Other components

- **CLI user**
- **Gemini API**
- **psutil process API**

## Connections

- CLI user → Scenario runner: selects scenario (evidence: `main.py`)
- Scenario runner → Load processes: spawns workloads (evidence: `main.py`)
- Scenario runner → Process metrics: collects metrics (evidence: `main.py`)
- Process metrics → psutil process API: samples process (evidence: `tools/process_metrics.py`)
- Scenario runner → Agent pipeline: runs analysis (evidence: `main.py`)
- Agent pipeline → Monitoring agent: dispatches first (evidence: `pipeline.py`)
- Monitoring agent → Bottleneck analysis: passes state (evidence: `pipeline.py`)
- Bottleneck analysis → Scaling decision: passes state (evidence: `pipeline.py`)
- Scaling decision → Recommendation: passes state (evidence: `pipeline.py`)
- Monitoring agent → Typed agent state: validates metrics (evidence: `agents/monitoring_agent.py`)
- Bottleneck analysis → Typed agent state: models results (evidence: `agents/bottleneck_agent.py`)
- Scaling decision → Typed agent state: models decision (evidence: `agents/scaling_agent.py`)
- Recommendation → Typed agent state: models result (evidence: `agents/recommendation_agent.py`)
- Agent pipeline → Typed agent state: types graph state (evidence: `pipeline.py`)
- Monitoring agent → LLM factory: requests summary (evidence: `agents/monitoring_agent.py`)
- Bottleneck analysis → LLM factory: requests diagnosis (evidence: `agents/bottleneck_agent.py`)
- Scaling decision → LLM factory: requests decision (evidence: `agents/scaling_agent.py`)
- Recommendation → LLM factory: requests narrative (evidence: `agents/recommendation_agent.py`)
- LLM factory → Gemini API: generates content (evidence: `agents/llm_factory.py`)
- Scenario runner → CLI user: displays report (evidence: `main.py`)
