# akshayasurala/multi-agent-negotiation-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/akshayasurala/multi-agent-negotiation-simulator
- Repository: https://github.com/akshayasurala/multi-agent-negotiation-simulator

## Overview

This is a real-estate negotiation platform for AI-vs-AI simulation and human practice. Users choose a property scenario and agent personalities, then negotiate through offers and decisions; the platform tracks rounds and outcomes and can produce transcripts and reports. The frontend calls a FastAPI backend, whose router coordinates negotiation flows, agents, session state, and reporting. The README documents capabilities beyond the sampled excerpts; edges to those capabilities are included only where documented, and unsampled implementation details are not inferred.

Main entry points: [`backend/routers/negotiation_router.py`](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/routers/negotiation_router.py) (Negotiation API), [`backend/agents/practice_agent.py`](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/practice_agent.py) (Practice Agent), [`src/main.jsx`](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/src/main.jsx) (Negotiation UI), [`backend/main.py`](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/main.py) (FastAPI Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_ui["Negotiation UI<br/>[main.jsx]"]
  node_api_client["API Client<br/>[negotiation-api.js]"]
  node_metrics["Negotiation Metrics"]
end

subgraph group_backend["Negotiation Backend"]
  node_api["FastAPI Application<br/>[main.py]"]
  node_router["Negotiation API"]
  node_sessions[("Practice Sessions<br/>[practice_store.py]")]
  node_runner["AI Negotiation Runner"]
  node_models["API Data Models<br/>[models.py]"]
end

subgraph group_agents["Negotiation Agents"]
  node_orchestrator["Turn Orchestrator"]
  node_evaluator["Counteroffer Evaluator"]
  node_deadlock["Deadlock Detector"]
  node_practice_agent["Practice Agent<br/>[practice_agent.py]"]
  node_reasoning["Reasoning Engine"]
end

subgraph group_property["Property and Reports"]
  node_scenario["Scenario Definitions<br/>[scenarios.py]"]
  node_personalities["Agent Personalities<br/>[personalities.py]"]
  node_dataset[("Property Dataset")]
  node_dataset_manager["Property Selection<br/>[dataset_manager.py]"]
  node_property_utils["Property Utilities<br/>[property_utils.py]"]
  node_reports["Reports and Transcripts"]
end

node_user(("User"))
node_llm{{"Gemini LLM"}}

node_user -->|"selects and negotiates"| node_ui
node_ui -->|"requests actions"| node_api_client
node_api_client -->|"calls API"| node_router
node_router -->|"routes through"| node_api
node_api -->|"loads dataset"| node_dataset_manager
node_api -->|"sets dataset"| node_router
node_router -->|"serves scenarios"| node_scenario
node_router -->|"serves personalities"| node_personalities
node_dataset_manager -.->|"reads properties"| node_dataset
node_router -->|"runs simulation"| node_runner
node_router -->|"coordinates turns"| node_orchestrator
node_runner -->|"uses agent logic"| node_practice_agent
node_router -->|"handles practice"| node_practice_agent
node_router -->|"evaluates offers"| node_evaluator
node_router -.->|"checks deadlocks"| node_deadlock
node_router -->|"stores session state"| node_sessions
node_practice_agent -->|"uses session model"| node_sessions
node_router -->|"requests reasoning"| node_reasoning
node_reasoning -->|"uses price formatting"| node_practice_agent
node_reasoning -->|"generates responses"| node_llm
node_router -->|"generates reports"| node_reports
node_router -->|"uses property helpers"| node_property_utils
node_router -->|"validates API data"| node_models
node_ui -->|"renders metrics"| node_metrics

click node_ui "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/src/main.jsx"
click node_api_client "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/frontend/services/negotiation-api.js"
click node_metrics "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/frontend/components/negotiation-metrics.js"
click node_api "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/main.py"
click node_router "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/routers/negotiation_router.py"
click node_sessions "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/practice_store.py"
click node_runner "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/negotiation_runner.py"
click node_orchestrator "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/orchestrator_agent.py"
click node_evaluator "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/counteroffer_evaluator.py"
click node_deadlock "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/deadlock_detector.py"
click node_practice_agent "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/practice_agent.py"
click node_reasoning "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/reasoning_engine.py"
click node_scenario "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/scenarios.py"
click node_personalities "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/personalities.py"
click node_dataset_manager "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/dataset_manager.py"
click node_property_utils "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/property_utils.py"
click node_reports "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/report_generator.py"
click node_models "https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/models.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_ui,node_api_client,node_metrics,node_user toneBlue
class node_api,node_router,node_sessions,node_runner,node_models toneAmber
class node_orchestrator,node_evaluator,node_deadlock,node_practice_agent,node_reasoning toneMint
class node_scenario,node_personalities,node_dataset,node_dataset_manager,node_property_utils,node_reports toneRose
class node_llm toneIndigo
```

## Components

### User Experience

- [Negotiation UI](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/src/main.jsx): `src/main.jsx`
- [API Client](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/frontend/services/negotiation-api.js): `frontend/services/negotiation-api.js`
- [Negotiation Metrics](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/frontend/components/negotiation-metrics.js): `frontend/components/negotiation-metrics.js`

### Negotiation Backend

- [FastAPI Application](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/main.py): `backend/main.py`
- [Negotiation API](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/routers/negotiation_router.py): `backend/routers/negotiation_router.py`
- [Practice Sessions](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/practice_store.py): `backend/agents/practice_store.py`
- [AI Negotiation Runner](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/negotiation_runner.py): `backend/negotiation_runner.py`
- [API Data Models](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/models.py): `backend/models.py`

### Negotiation Agents

- [Turn Orchestrator](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/orchestrator_agent.py): `backend/agents/orchestrator_agent.py`
- [Counteroffer Evaluator](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/counteroffer_evaluator.py): `backend/agents/counteroffer_evaluator.py`
- [Deadlock Detector](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/deadlock_detector.py): `backend/agents/deadlock_detector.py`
- [Practice Agent](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/practice_agent.py): `backend/agents/practice_agent.py`
- [Reasoning Engine](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/agents/reasoning_engine.py): `backend/agents/reasoning_engine.py`

### Property and Reports

- [Scenario Definitions](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/scenarios.py): `backend/scenarios.py`
- [Agent Personalities](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/personalities.py): `backend/personalities.py`
- **Property Dataset**
- [Property Selection](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/dataset_manager.py): `backend/dataset_manager.py`
- [Property Utilities](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/property_utils.py): `backend/property_utils.py`
- [Reports and Transcripts](https://github.com/akshayasurala/multi-agent-negotiation-simulator/blob/main/backend/report_generator.py): `backend/report_generator.py`

### Other components

- **User**
- **Gemini LLM**

## Connections

- User → Negotiation UI: selects and negotiates
- Negotiation UI → API Client: requests actions (evidence: `src/main.jsx`)
- API Client → Negotiation API: calls API
- Negotiation API → FastAPI Application: routes through (evidence: `backend/main.py`)
- FastAPI Application → Property Selection: loads dataset (evidence: `backend/main.py`)
- FastAPI Application → Negotiation API: sets dataset (evidence: `backend/main.py`)
- Negotiation API → Scenario Definitions: serves scenarios
- Negotiation API → Agent Personalities: serves personalities
- Property Selection → Property Dataset: reads properties
- Negotiation API → AI Negotiation Runner: runs simulation (evidence: `backend/routers/negotiation_router.py`)
- Negotiation API → Turn Orchestrator: coordinates turns (evidence: `backend/routers/negotiation_router.py`)
- AI Negotiation Runner → Practice Agent: uses agent logic (evidence: `backend/negotiation_runner.py`)
- Negotiation API → Practice Agent: handles practice (evidence: `backend/routers/negotiation_router.py`)
- Negotiation API → Counteroffer Evaluator: evaluates offers (evidence: `backend/routers/negotiation_router.py`)
- Negotiation API → Deadlock Detector: checks deadlocks
- Negotiation API → Practice Sessions: stores session state (evidence: `backend/routers/negotiation_router.py`)
- Practice Agent → Practice Sessions: uses session model (evidence: `backend/agents/practice_agent.py`)
- Negotiation API → Reasoning Engine: requests reasoning (evidence: `backend/routers/negotiation_router.py`)
- Reasoning Engine → Practice Agent: uses price formatting (evidence: `backend/agents/reasoning_engine.py`)
- Reasoning Engine → Gemini LLM: generates responses (evidence: `backend/agents/reasoning_engine.py`)
- Negotiation API → Reports and Transcripts: generates reports (evidence: `backend/routers/negotiation_router.py`)
- Negotiation API → Property Utilities: uses property helpers (evidence: `backend/routers/negotiation_router.py`)
- Negotiation API → API Data Models: validates API data (evidence: `backend/routers/negotiation_router.py`)
- Negotiation UI → Negotiation Metrics: renders metrics (evidence: `src/main.jsx`)
