# nethermindeth/agentarena-arbiter architecture

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

- Interactive diagram: https://gitdiagram.com/nethermindeth/agentarena-arbiter
- Repository: https://github.com/nethermindeth/agentarena-arbiter

## Overview

1. **What this repo is**
   ArbiterAgent is a Python triage service for vulnerability reports. Its job is to take multiple agent-submitted findings, normalize them, deduplicate overlaps, score severity, and persist or return the consolidated result.

2. **Top-level structure**
   The architecture is centered in `Demo/app/`:
   - `main.py` is the application entrypoint and likely exposes the API surface.
   - `core/` contains the triage logic.
   - `models/` defines the input/output data shapes.
   - `database/` contains persistence access, specifically MongoDB handling.
   - `config.py`, `types.py`, and `task_utils.py` hold shared runtime configuration and orchestration utilities.

3. **Request/response boundary**
   The system’s main external boundary is a JSON-based API. Incoming finding payloads are parsed into structured models from `models/finding_input.py`, processed by the core pipeline, and emitted back as consolidated findings, likely using `models/finding_db.py` for persisted/normalized records.

4. **Core processing pipeline**
   The main internal flow is:
   input findings → validation/modeling → deduplication → severity/evaluation → output assembly.  
   `core/deduplication.py` is the key module for grouping or merging similar reports. `core/evaluation.py` appears responsible for scoring or classifying findings after deduplication.

5. **LLM/model integration layer**
   `core/claude_model.py` and `core/gemini_model.py` indicate the service can delegate parts of triage to different AI providers. These modules form an abstraction boundary between the deterministic orchestration code and external model APIs.

6. **Prompt and decision support**
   `core/prompt_utils.py` suggests prompt construction is separated from the model adapters. This keeps prompt logic centralized and reusable across providers, which matters if the same triage rules are sent to Claude or Gemini with different wrappers.

7. **Persistence layer**
   `database/mongodb_handler.py` is the repository’s storage boundary. It likely stores findings, deduplication results, or workflow state in MongoDB. The presence of `docker-compose.yml` strongly suggests MongoDB is part of the local development/runtime stack.

8. **Data models and contracts**
   `models/finding_input.py` and `models/finding_db.py` define the schema boundary between untrusted incoming report data and internal/persisted records. This separation is important for an architecture diagram because it shows where validation and normalization happen.

9. **Orchestration and runtime behavior**
   `task_utils.py` and `types.py` imply some shared workflow coordination and typed domain objects. These likely connect API handlers, deduplication, model calls, and persistence into one execution path.

10. **Configuration and deployment**
   `config.py`, `.env.example`, `Dockerfile`, and `docker-compose.yml` show the service is containerized and environment-driven. The repo also includes GitHub Actions workflows for `ci-staging` and `ci-prod`, indicating separate build/test/deploy paths for staging and production.

11. **Quality and verification boundary**
   The test suite is split into unit and integration tests, which reveals the intended seams of the system:
   - unit tests for prompt logic, deduplication, evaluation, cache, and task processing
   - integration tests for API behavior, caching, database interaction, model integration, and end-to-end workflow  
   This suggests the architecture is designed around testable service boundaries rather than a monolith of tightly coupled code.

12. **How to draw the diagram**
   A good architecture diagram would show:
   external clients → API entrypoint (`main.py`) → validation/models → deduplication/evaluation core → optional LLM provider adapters (Claude/Gemini via prompt utilities) → MongoDB persistence → JSON response.  
   Cross-cutting concerns include configuration/env, containerization, and CI/CD workflows.

Main entry points: [`Demo/app/core/evaluation.py`](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/evaluation.py) (Severity scoring), [`Demo/tests/integration`](https://github.com/nethermindeth/agentarena-arbiter/tree/main/Demo/tests/integration) (Integration tests), [`Demo/app/task_utils.py`](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/task_utils.py) (Task utils), [`Demo/app/core/prompt_utils.py`](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/prompt_utils.py) (Prompt builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Service"]
  node_main["API entry<br/>entrypoint<br/>[main.py]"]
  node_task_utils["Task utils<br/>orchestration<br/>[task_utils.py]"]
  node_types["Domain types<br/>contracts<br/>[types.py]"]
  node_finding_input["Input model<br/>schema<br/>[finding_input.py]"]
  node_finding_db["Persisted model<br/>schema<br/>[finding_db.py]"]
  node_deduplication{{"Dedup engine<br/>triage<br/>[deduplication.py]"}}
  node_evaluation{{"Severity scoring<br/>triage<br/>[evaluation.py]"}}
  node_prompt_utils["Prompt builder<br/>llm-support<br/>[prompt_utils.py]"]
  node_claude_model["Claude adapter<br/>llm-adapter<br/>[claude_model.py]"]
  node_gemini_model["Gemini adapter<br/>llm-adapter<br/>[gemini_model.py]"]
  node_mongodb_handler[("Mongo handler<br/>persistence<br/>[mongodb_handler.py]")]
end

subgraph group_infra["Runtime"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_dockerfile["Dockerfile<br/>container"]
  node_compose["Compose stack<br/>runtime-stack<br/>[docker-compose.yml]"]
  node_workflow_staging["CI staging<br/>workflow<br/>[ci-staging.yaml]"]
  node_workflow_prod["CI prod<br/>workflow<br/>[ci-prod.yaml]"]
end

subgraph group_tests["Tests"]
  node_unit_tests["Unit tests<br/>verification"]
  node_integration_tests["Integration tests<br/>verification"]
end

node_main -->|"parse"| node_finding_input
node_main -->|"orchestrate"| node_task_utils
node_task_utils -->|"dedupe"| node_deduplication
node_task_utils -->|"score"| node_evaluation
node_task_utils -->|"persist"| node_mongodb_handler
node_deduplication -->|"normalize"| node_finding_db
node_evaluation -->|"annotate"| node_finding_db
node_deduplication -->|"prompt"| node_prompt_utils
node_evaluation -->|"prompt"| node_prompt_utils
node_prompt_utils -->|"send"| node_claude_model
node_prompt_utils -->|"send"| node_gemini_model
node_claude_model -->|"assist"| node_evaluation
node_gemini_model -->|"assist"| node_evaluation
node_finding_input -->|"share types"| node_types
node_finding_db -->|"share types"| node_types
node_main -->|"load"| node_config
node_mongodb_handler -.->|"backed by"| node_compose
node_dockerfile -.->|"build"| node_compose
node_workflow_staging -.->|"build"| node_dockerfile
node_workflow_prod -.->|"build"| node_dockerfile
node_unit_tests -.->|"verify"| node_deduplication
node_unit_tests -.->|"verify"| node_evaluation
node_unit_tests -.->|"verify"| node_prompt_utils
node_unit_tests -.->|"verify"| node_task_utils
node_integration_tests -.->|"verify"| node_main
node_integration_tests -.->|"verify"| node_mongodb_handler
node_integration_tests -.->|"verify"| node_claude_model
node_integration_tests -.->|"verify"| node_gemini_model
node_integration_tests -.->|"verify"| node_finding_input

click node_main "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/main.py"
click node_config "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/config.py"
click node_task_utils "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/task_utils.py"
click node_types "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/types.py"
click node_finding_input "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/models/finding_input.py"
click node_finding_db "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/models/finding_db.py"
click node_deduplication "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/deduplication.py"
click node_evaluation "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/evaluation.py"
click node_prompt_utils "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/prompt_utils.py"
click node_claude_model "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/claude_model.py"
click node_gemini_model "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/gemini_model.py"
click node_mongodb_handler "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/database/mongodb_handler.py"
click node_dockerfile "https://github.com/nethermindeth/agentarena-arbiter/tree/main/Demo/Dockerfile"
click node_compose "https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/docker-compose.yml"
click node_workflow_staging "https://github.com/nethermindeth/agentarena-arbiter/blob/main/.github/workflows/ci-staging.yaml"
click node_workflow_prod "https://github.com/nethermindeth/agentarena-arbiter/blob/main/.github/workflows/ci-prod.yaml"
click node_unit_tests "https://github.com/nethermindeth/agentarena-arbiter/tree/main/Demo/tests/unit"
click node_integration_tests "https://github.com/nethermindeth/agentarena-arbiter/tree/main/Demo/tests/integration"

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_task_utils,node_types,node_finding_input,node_finding_db,node_deduplication,node_evaluation,node_prompt_utils,node_claude_model,node_gemini_model,node_mongodb_handler toneBlue
class node_config,node_dockerfile,node_compose,node_workflow_staging,node_workflow_prod toneAmber
class node_unit_tests,node_integration_tests toneMint
```

## Components

### Service

Python triage service and its runtime modules

- [API entry](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/main.py): entrypoint · Starts the service and exposes the request boundary · `Demo/app/main.py`
- [Task utils](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/task_utils.py): orchestration · Shared workflow helpers for triage execution · `Demo/app/task_utils.py`
- [Domain types](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/types.py): contracts · Shared typed objects used across the service · `Demo/app/types.py`
- [Input model](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/models/finding_input.py): schema · Validates and structures incoming finding payloads · `Demo/app/models/finding_input.py`
- [Persisted model](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/models/finding_db.py): schema · Normalized record shape used for storage and output · `Demo/app/models/finding_db.py`
- [Dedup engine](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/deduplication.py): triage · Groups and merges overlapping vulnerability reports · `Demo/app/core/deduplication.py`
- [Severity scoring](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/evaluation.py): triage · Classifies and scores consolidated findings · `Demo/app/core/evaluation.py`
- [Prompt builder](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/prompt_utils.py): llm-support · Constructs reusable prompts for model-backed triage · `Demo/app/core/prompt_utils.py`
- [Claude adapter](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/claude_model.py): llm-adapter · Provider wrapper for Claude-based triage steps · `Demo/app/core/claude_model.py`
- [Gemini adapter](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/core/gemini_model.py): llm-adapter · Provider wrapper for Gemini-based triage steps · `Demo/app/core/gemini_model.py`
- [Mongo handler](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/database/mongodb_handler.py): persistence · MongoDB access for storing and retrieving triage data · `Demo/app/database/mongodb_handler.py`

### Runtime

Container, config, and deployment boundaries

- [Config](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/app/config.py): settings · Runtime configuration and environment wiring · `Demo/app/config.py`
- [Dockerfile](https://github.com/nethermindeth/agentarena-arbiter/tree/main/Demo/Dockerfile): container · Container image definition for the service · `Demo/Dockerfile`
- [Compose stack](https://github.com/nethermindeth/agentarena-arbiter/blob/main/Demo/docker-compose.yml): runtime-stack · Local service stack including MongoDB · `Demo/docker-compose.yml`
- [CI staging](https://github.com/nethermindeth/agentarena-arbiter/blob/main/.github/workflows/ci-staging.yaml): workflow · GitHub Actions path for staging validation and delivery · `.github/workflows/ci-staging.yaml`
- [CI prod](https://github.com/nethermindeth/agentarena-arbiter/blob/main/.github/workflows/ci-prod.yaml): workflow · GitHub Actions path for production validation and delivery · `.github/workflows/ci-prod.yaml`

### Tests

Unit and integration verification boundaries

- [Unit tests](https://github.com/nethermindeth/agentarena-arbiter/tree/main/Demo/tests/unit): verification · Fast checks for deduplication, evaluation, prompts, and task logic · `Demo/tests/unit`
- [Integration tests](https://github.com/nethermindeth/agentarena-arbiter/tree/main/Demo/tests/integration): verification · End-to-end checks for API, cache, database, models, and workflow behavior · `Demo/tests/integration`

## Connections

- API entry → Input model: parse · API requests are converted into validated input findings
- API entry → Task utils: orchestrate · Main entrypoint coordinates the triage workflow
- Task utils → Dedup engine: dedupe · Workflow routes findings through deduplication
- Task utils → Severity scoring: score · Workflow applies severity or risk evaluation
- Task utils → Mongo handler: persist · Consolidated results can be stored in MongoDB
- Dedup engine → Persisted model: normalize · Merged results are shaped into persisted records
- Severity scoring → Persisted model: annotate · Scored findings are assembled into output records
- Dedup engine → Prompt builder: prompt · Dedup logic can prepare model-facing instructions
- Severity scoring → Prompt builder: prompt · Evaluation can reuse centralized prompt construction
- Prompt builder → Claude adapter: send · Prompts are executed through the Claude adapter
- Prompt builder → Gemini adapter: send · Prompts are executed through the Gemini adapter
- Claude adapter → Severity scoring: assist · Model output feeds triage classification
- Gemini adapter → Severity scoring: assist · Model output feeds triage classification
- Input model → Domain types: share types · Input schema relies on shared domain types
- Persisted model → Domain types: share types · Persisted schema relies on shared domain types
- API entry → Config: load · Service startup consumes environment configuration
- Mongo handler → Compose stack: backed by · Local runtime stack includes MongoDB service
- Dockerfile → Compose stack: build · Compose stack is built from the container image
- CI staging → Dockerfile: build · Staging pipeline builds the containerized service
- CI prod → Dockerfile: build · Production pipeline builds the containerized service
- Unit tests → Dedup engine: verify · Unit tests cover core deduplication behavior
- Unit tests → Severity scoring: verify · Unit tests cover scoring and classification logic
- Unit tests → Prompt builder: verify · Unit tests cover prompt construction
- Unit tests → Task utils: verify · Unit tests cover workflow helpers
- Integration tests → API entry: verify · Integration tests exercise the API boundary
- Integration tests → Mongo handler: verify · Integration tests cover database interaction
- Integration tests → Claude adapter: verify · Integration tests cover model-provider integration
- Integration tests → Gemini adapter: verify · Integration tests cover model-provider integration
- Integration tests → Input model: verify · Integration tests cover model parsing and validation
