# mizcausevic-dev/evidence-ranking-engine architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/evidence-ranking-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/evidence-ranking-engine
- Repository: https://github.com/mizcausevic-dev/evidence-ranking-engine

## Overview

This is a FastAPI evidence-ranking service with operator-facing HTML surfaces and JSON endpoints. The main workflow accepts a prompt-fit ranking request, evaluates seeded evidence using trust, citation, freshness, and contradiction signals, then returns ranked packets, a posture, and recommended next action. The service also provides dashboard summaries, packet lookup, conflict review pressure, and owner stewardship lanes. The source confirms seeded in-process data rather than a persistent store; the broader documented capabilities are represented without inferring unsampled route internals.

Main entry points: [`app/main.py`](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/main.py) (JSON endpoints), [`app/render.py`](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/render.py) (Operator pages), [`app/services/evidence_ranking_service.py`](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py) (Packet ranking), [`app/data/sample_evidence_data.py`](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/data/sample_evidence_data.py) (Seeded evidence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["API and operator surfaces"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_html["Operator pages<br/>[render.py]"]
  node_jsonapi["JSON endpoints<br/>[main.py]"]
end

subgraph group_ranking["Evidence analysis"]
  node_rank["Packet ranking"]
  node_promptfit["Prompt-fit ranking"]
  node_conflicts["Conflict pressure"]
  node_stewardship["Owner lanes"]
  node_summary["Dashboard summary"]
end

subgraph group_data["Evidence inputs"]
  node_seed["Seeded evidence"]
end

node_operator(("Decision operator"))
node_client(("API/page response"))

node_operator -->|"requests"| node_fastapi
node_fastapi -->|"renders pages"| node_html
node_fastapi -->|"dispatches routes"| node_jsonapi
node_html -->|"loads summary"| node_summary
node_html -->|"loads packets"| node_rank
node_html -->|"loads conflicts"| node_conflicts
node_html -->|"loads owners"| node_stewardship
node_jsonapi -->|"requests packets"| node_rank
node_jsonapi -->|"evaluates prompt"| node_promptfit
node_jsonapi -->|"requests conflicts"| node_conflicts
node_jsonapi -->|"requests lanes"| node_stewardship
node_jsonapi -->|"requests summary"| node_summary
node_rank -->|"reads packets"| node_seed
node_summary -->|"reads dashboard"| node_seed
node_promptfit -->|"ranks packets"| node_rank
node_conflicts -->|"filters ranked packets"| node_rank
node_stewardship -->|"reads ownership"| node_seed
node_jsonapi -->|"returns JSON"| node_client
node_html -->|"returns HTML"| node_client

click node_fastapi "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/main.py"
click node_html "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/render.py"
click node_jsonapi "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/main.py"
click node_rank "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py"
click node_promptfit "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py"
click node_conflicts "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py"
click node_stewardship "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py"
click node_summary "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py"
click node_seed "https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/data/sample_evidence_data.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_fastapi,node_html,node_jsonapi toneBlue
class node_rank,node_promptfit,node_conflicts,node_stewardship,node_summary toneAmber
class node_seed,node_client toneMint
class node_operator toneIndigo
```

## Components

### API and operator surfaces

- [FastAPI routes](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/main.py): `app/main.py`
- [Operator pages](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/render.py): `app/render.py`
- [JSON endpoints](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/main.py): `app/main.py`

### Evidence analysis

- [Packet ranking](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py): `app/services/evidence_ranking_service.py`
- [Prompt-fit ranking](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py): `app/services/evidence_ranking_service.py`
- [Conflict pressure](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py): `app/services/evidence_ranking_service.py`
- [Owner lanes](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py): `app/services/evidence_ranking_service.py`
- [Dashboard summary](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/services/evidence_ranking_service.py): `app/services/evidence_ranking_service.py`

### Evidence inputs

- [Seeded evidence](https://github.com/mizcausevic-dev/evidence-ranking-engine/blob/main/app/data/sample_evidence_data.py): `app/data/sample_evidence_data.py`

### Other components

- **Decision operator**
- **API/page response**

## Connections

- Decision operator → FastAPI routes: requests
- FastAPI routes → Operator pages: renders pages
- FastAPI routes → JSON endpoints: dispatches routes
- Operator pages → Dashboard summary: loads summary
- Operator pages → Packet ranking: loads packets
- Operator pages → Conflict pressure: loads conflicts
- Operator pages → Owner lanes: loads owners
- JSON endpoints → Packet ranking: requests packets
- JSON endpoints → Prompt-fit ranking: evaluates prompt
- JSON endpoints → Conflict pressure: requests conflicts
- JSON endpoints → Owner lanes: requests lanes
- JSON endpoints → Dashboard summary: requests summary
- Packet ranking → Seeded evidence: reads packets
- Dashboard summary → Seeded evidence: reads dashboard
- Prompt-fit ranking → Packet ranking: ranks packets
- Conflict pressure → Packet ranking: filters ranked packets
- Owner lanes → Seeded evidence: reads ownership
- JSON endpoints → API/page response: returns JSON
- Operator pages → API/page response: returns HTML