# shreya-1831/mil-evid architecture

> Architecture diagram of the GitHub repository shreya-1831/mil-evid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shreya-1831/mil-evid
- Repository: https://github.com/shreya-1831/mil-evid

## Overview

MIL-EVID is an evidence-ingestion and retrieval-augmented analysis prototype: source records are mapped, preprocessed, chunked, and stored; analysis code retrieves and reranks evidence, builds a guarded context, and generates a structured analysis. The sampled application exposes a health route, but does not show an API route invoking the analysis service. README-described perspectives and dynamic evidence are broader or planned capabilities; their wiring is not established by the sampled source.

Main entry points: [`backend/app/services/analysis_service.py`](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/services/analysis_service.py) (Analysis service), [`backend/app/modules/preprocessing/pipeline.py`](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/pipeline.py) (Preprocessing pipeline), [`backend/app/services/evidence_ingestion_service.py`](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/services/evidence_ingestion_service.py) (Ingestion service), [`backend/app/modules/retrieval/hybrid_retriever.py`](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/hybrid_retriever.py) (Hybrid retriever)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Evidence ingestion"]
  node_static_runner["Static runners"]
  node_csv_ingest["CSV ingestion"]
  node_source_mappers["Source mappers"]
  node_ingestion_service["Ingestion service"]
  node_preprocessing["Preprocessing pipeline<br/>[pipeline.py]"]
  node_cleaner["Cleaning<br/>[cleaner.py]"]
  node_normalizer["Normalization<br/>[normalizer.py]"]
  node_deduplicator["Deduplication<br/>[deduplicator.py]"]
  node_chunker["Chunking<br/>[chunker.py]"]
end

subgraph group_storage["Evidence storage"]
  node_chunk_store[("Chunk text store")]
  node_metadata_repository["Metadata repository"]
  node_postgres[("PostgreSQL metadata<br/>[models.py]")]
end

subgraph group_retrieval["Hybrid retrieval"]
  node_hybrid_retriever["Hybrid retriever"]
  node_bm25["BM25 search<br/>[bm25_index.py]"]
  node_faiss["FAISS search<br/>[faiss_index.py]"]
  node_rrf["Rank fusion<br/>[rrf.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
end

subgraph group_analysis["Analysis application"]
  node_analysis_service["Analysis service"]
  node_context_builder["Context builder<br/>[context_builder.py]"]
  node_evidence_guard["Evidence guard<br/>[evidence_guard.py]"]
  node_analyzer["Evidence analyzer<br/>[analyzer.py]"]
  node_llm_client["Ollama client<br/>[llm_client.py]"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_health_route["Health route<br/>[health.py]"]
end

node_source_operator(("Ingestion operator"))
node_analyst(("Analyst"))

node_source_operator -->|"starts ingestion"| node_static_runner
node_static_runner -->|"runs CSV"| node_csv_ingest
node_static_runner -->|"selects mapper"| node_source_mappers
node_csv_ingest -->|"maps records"| node_source_mappers
node_csv_ingest -->|"sends batches"| node_ingestion_service
node_ingestion_service -->|"processes documents"| node_preprocessing
node_preprocessing -->|"cleans"| node_cleaner
node_preprocessing -->|"normalizes"| node_normalizer
node_preprocessing -->|"deduplicates"| node_deduplicator
node_preprocessing -->|"chunks"| node_chunker
node_ingestion_service -->|"appends chunks"| node_chunk_store
node_ingestion_service -->|"persists metadata"| node_metadata_repository
node_metadata_repository -->|"writes metadata"| node_postgres
node_analyst -.->|"submits query"| node_analysis_service
node_analysis_service -->|"searches evidence"| node_hybrid_retriever
node_hybrid_retriever -->|"lexical search"| node_bm25
node_hybrid_retriever -->|"dense search"| node_faiss
node_hybrid_retriever -->|"fuses ranks"| node_rrf
node_analysis_service -->|"reads chunk text"| node_chunk_store
node_analysis_service -->|"reranks candidates"| node_reranker
node_analysis_service -->|"builds context"| node_context_builder
node_analysis_service -->|"filters evidence"| node_evidence_guard
node_analysis_service -->|"analyzes context"| node_analyzer
node_api_app -->|"registers route"| node_health_route
node_analyzer -.->|"generates analysis"| node_llm_client

click node_static_runner "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/ingestion/static_ingestion_runner.py"
click node_csv_ingest "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/ingestion/static_ingestion.py"
click node_source_mappers "https://github.com/shreya-1831/mil-evid/tree/main/backend/app/modules/ingestion"
click node_ingestion_service "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/services/evidence_ingestion_service.py"
click node_preprocessing "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/pipeline.py"
click node_cleaner "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/cleaner.py"
click node_normalizer "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/normalizer.py"
click node_deduplicator "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/deduplicator.py"
click node_chunker "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/chunker.py"
click node_chunk_store "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/repositories/chunk_file_store.py"
click node_metadata_repository "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/repositories/evidence_repository.py"
click node_postgres "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/database/models.py"
click node_hybrid_retriever "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/hybrid_retriever.py"
click node_bm25 "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/bm25_index.py"
click node_faiss "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/faiss_index.py"
click node_rrf "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/rrf.py"
click node_reranker "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/reranker.py"
click node_analysis_service "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/services/analysis_service.py"
click node_context_builder "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/context_builder.py"
click node_evidence_guard "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/evidence_guard.py"
click node_analyzer "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/analyzer.py"
click node_llm_client "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/llm_client.py"
click node_api_app "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/main.py"
click node_health_route "https://github.com/shreya-1831/mil-evid/blob/main/backend/app/api/routes/health.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_static_runner,node_csv_ingest,node_source_mappers,node_ingestion_service,node_preprocessing,node_cleaner,node_normalizer,node_deduplicator,node_chunker toneBlue
class node_chunk_store,node_metadata_repository,node_postgres toneAmber
class node_hybrid_retriever,node_bm25,node_faiss,node_rrf,node_reranker toneMint
class node_analysis_service,node_context_builder,node_evidence_guard,node_analyzer,node_llm_client,node_api_app,node_health_route toneRose
class node_source_operator,node_analyst toneIndigo
```

## Components

### Evidence ingestion

- [Static runners](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/ingestion/static_ingestion_runner.py): `backend/app/modules/ingestion/static_ingestion_runner.py`
- [CSV ingestion](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/ingestion/static_ingestion.py): `backend/app/modules/ingestion/static_ingestion.py`
- [Source mappers](https://github.com/shreya-1831/mil-evid/tree/main/backend/app/modules/ingestion): `backend/app/modules/ingestion`
- [Ingestion service](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/services/evidence_ingestion_service.py): `backend/app/services/evidence_ingestion_service.py`
- [Preprocessing pipeline](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/pipeline.py): `backend/app/modules/preprocessing/pipeline.py`
- [Cleaning](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/cleaner.py): `backend/app/modules/preprocessing/cleaner.py`
- [Normalization](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/normalizer.py): `backend/app/modules/preprocessing/normalizer.py`
- [Deduplication](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/deduplicator.py): `backend/app/modules/preprocessing/deduplicator.py`
- [Chunking](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/preprocessing/chunker.py): `backend/app/modules/preprocessing/chunker.py`

### Evidence storage

- [Chunk text store](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/repositories/chunk_file_store.py): `backend/app/repositories/chunk_file_store.py`
- [Metadata repository](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/repositories/evidence_repository.py): `backend/app/repositories/evidence_repository.py`
- [PostgreSQL metadata](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/database/models.py): `backend/app/database/models.py`

### Hybrid retrieval

- [Hybrid retriever](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/hybrid_retriever.py): `backend/app/modules/retrieval/hybrid_retriever.py`
- [BM25 search](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/bm25_index.py): `backend/app/modules/retrieval/bm25_index.py`
- [FAISS search](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/faiss_index.py): `backend/app/modules/retrieval/faiss_index.py`
- [Rank fusion](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/rrf.py): `backend/app/modules/retrieval/rrf.py`
- [Cross-encoder reranker](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/retrieval/reranker.py): `backend/app/modules/retrieval/reranker.py`

### Analysis application

- [Analysis service](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/services/analysis_service.py): `backend/app/services/analysis_service.py`
- [Context builder](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/context_builder.py): `backend/app/modules/analysis/context_builder.py`
- [Evidence guard](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/evidence_guard.py): `backend/app/modules/analysis/evidence_guard.py`
- [Evidence analyzer](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/analyzer.py): `backend/app/modules/analysis/analyzer.py`
- [Ollama client](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/modules/analysis/llm_client.py): `backend/app/modules/analysis/llm_client.py`
- [FastAPI app](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/main.py): `backend/app/main.py`
- [Health route](https://github.com/shreya-1831/mil-evid/blob/main/backend/app/api/routes/health.py): `backend/app/api/routes/health.py`

### Other components

- **Ingestion operator**
- **Analyst**

## Connections

- Ingestion operator → Static runners: starts ingestion
- Static runners → CSV ingestion: runs CSV
- Static runners → Source mappers: selects mapper
- CSV ingestion → Source mappers: maps records
- CSV ingestion → Ingestion service: sends batches
- Ingestion service → Preprocessing pipeline: processes documents
- Preprocessing pipeline → Cleaning: cleans
- Preprocessing pipeline → Normalization: normalizes
- Preprocessing pipeline → Deduplication: deduplicates
- Preprocessing pipeline → Chunking: chunks
- Ingestion service → Chunk text store: appends chunks
- Ingestion service → Metadata repository: persists metadata
- Metadata repository → PostgreSQL metadata: writes metadata
- Analyst → Analysis service: submits query
- Analysis service → Hybrid retriever: searches evidence
- Hybrid retriever → BM25 search: lexical search
- Hybrid retriever → FAISS search: dense search
- Hybrid retriever → Rank fusion: fuses ranks
- Analysis service → Chunk text store: reads chunk text
- Analysis service → Cross-encoder reranker: reranks candidates
- Analysis service → Context builder: builds context
- Analysis service → Evidence guard: filters evidence
- Analysis service → Evidence analyzer: analyzes context
- FastAPI app → Health route: registers route
- Evidence analyzer → Ollama client: generates analysis