# muradyanhaykaz05-blip/electronic-comms-law-qa architecture

> Architecture diagram of the GitHub repository muradyanhaykaz05-blip/electronic-comms-law-qa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muradyanhaykaz05-blip/electronic-comms-law-qa
- Repository: https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa

## Overview

This is a bilingual legal-question-answering RAG application. Users ask in Armenian or English; the API retrieves law excerpts, builds a language-appropriate prompt, calls a configured LLM, and checks article citations. A separate benchmark workflow scores answers for accuracy and hallucinations and reports operational metrics. The README documents ingestion and database loading; sampled source confirms the retrieval and scoring paths. Unsampled implementation details and some runtime wiring are represented only where the README supports them.

Main entry points: [`app.py`](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/app.py) (Ask workflow), [`providers/__init__.py`](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/__init__.py) (Provider registry), [`rag/retriever.py`](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/retriever.py) (Hybrid retrieval), [`providers/base.py`](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/base.py) (Provider interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_web_ui["Web interface<br/>[index.html]"]
  node_web_client["Browser client<br/>[app.js]"]
end

subgraph group_api["API workflows"]
  node_api_server["FastAPI server<br/>[app.py]"]
  node_ask_flow["Ask workflow<br/>[app.py]"]
  node_benchmark_flow["Benchmark runner<br/>[app.py]"]
  node_benchmark_set["Question set<br/>[questions.json]"]
end

subgraph group_rag["Retrieval and scoring"]
  node_retrieval["Hybrid retrieval<br/>[retriever.py]"]
  node_embedding["Query embeddings<br/>[retriever.py]"]
  node_pg_store["Postgres search<br/>[pgvector_store.py]"]
  node_prompt_context["Context and prompt<br/>[pipeline.py]"]
  node_article_numbers["Citation parsing<br/>[article_numbers.py]"]
  node_groundedness["Citation checking<br/>[pipeline.py]"]
  node_judge_scoring["Judge scoring<br/>[scoring.py]"]
end

subgraph group_providers["LLM providers"]
  node_provider_registry["Provider registry<br/>[__init__.py]"]
  node_provider_base["Provider interface<br/>[base.py]"]
  node_gemini["Gemini adapter<br/>[gemini_provider.py]"]
  node_openai["OpenAI adapter<br/>[openai_provider.py]"]
  node_grok["Grok adapter<br/>[grok_provider.py]"]
  node_openrouter["OpenRouter adapter"]
  node_pricing["Cost estimates<br/>[pricing.py]"]
end

subgraph group_corpus["Law corpus"]
  node_law_db[("Law chunk store<br/>[schema.sql]")]
  node_ingest_hy["Armenian ingestion<br/>[ingest.py]"]
  node_ingest_en["English ingestion<br/>[ingest_en.py]"]
  node_article_data["Pre-ingested articles<br/>[articles.json]"]
  node_article_data_en["English articles<br/>[articles_en.json]"]
  node_loader["Embedding loader"]
end

node_user(("Questioner"))
node_provider_services["LLM services"]

node_user -->|"asks"| node_web_client
node_web_client -->|"calls API"| node_api_server
node_api_server -->|"serves"| node_web_ui
node_api_server -->|"routes ask"| node_ask_flow
node_api_server -->|"routes benchmark"| node_benchmark_flow
node_ask_flow -->|"builds context"| node_retrieval
node_retrieval -->|"encodes query"| node_embedding
node_retrieval -->|"searches"| node_pg_store
node_pg_store -->|"queries"| node_law_db
node_ask_flow -->|"builds prompt"| node_prompt_context
node_prompt_context -->|"retrieves chunks"| node_retrieval
node_ask_flow -->|"selects provider"| node_provider_registry
node_provider_registry -->|"configures"| node_gemini
node_provider_registry -->|"configures"| node_openai
node_provider_registry -->|"configures"| node_grok
node_provider_registry -->|"configures"| node_openrouter
node_gemini -->|"implements"| node_provider_base
node_grok -->|"extends"| node_provider_base
node_openrouter -->|"extends"| node_provider_base
node_openai -->|"implements"| node_provider_base
node_ask_flow -->|"checks citations"| node_groundedness
node_groundedness -->|"parses numbers"| node_article_numbers
node_benchmark_flow -->|"loads questions"| node_benchmark_set
node_benchmark_flow -->|"builds contexts"| node_retrieval
node_benchmark_flow -->|"scores answers"| node_judge_scoring
node_judge_scoring -->|"calls judge"| node_provider_base
node_benchmark_flow -->|"estimates cost"| node_pricing
node_gemini -->|"streams responses"| node_provider_services
node_grok -->|"calls API"| node_provider_services
node_openrouter -->|"calls API"| node_provider_services
node_ingest_hy -.->|"produces"| node_article_data
node_ingest_en -.->|"produces"| node_article_data_en
node_article_data -->|"loads chunks"| node_loader
node_article_data_en -->|"loads chunks"| node_loader
node_loader -->|"embeds and upserts"| node_law_db

click node_web_ui "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/static/index.html"
click node_web_client "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/static/app.js"
click node_api_server "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/app.py"
click node_ask_flow "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/app.py"
click node_benchmark_flow "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/app.py"
click node_benchmark_set "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/benchmark/questions.json"
click node_retrieval "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/retriever.py"
click node_embedding "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/retriever.py"
click node_pg_store "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/pgvector_store.py"
click node_law_db "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/db/schema.sql"
click node_prompt_context "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/pipeline.py"
click node_article_numbers "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/article_numbers.py"
click node_groundedness "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/pipeline.py"
click node_judge_scoring "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/scoring.py"
click node_provider_registry "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/__init__.py"
click node_provider_base "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/base.py"
click node_gemini "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/gemini_provider.py"
click node_openai "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/openai_provider.py"
click node_grok "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/grok_provider.py"
click node_openrouter "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/openrouter_provider.py"
click node_pricing "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/pricing.py"
click node_ingest_hy "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/ingest.py"
click node_ingest_en "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/ingest_en.py"
click node_article_data "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/articles.json"
click node_article_data_en "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/articles_en.json"
click node_loader "https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/load_to_pgvector.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_web_ui,node_web_client toneBlue
class node_api_server,node_ask_flow,node_benchmark_flow,node_benchmark_set toneAmber
class node_retrieval,node_embedding,node_pg_store,node_prompt_context,node_article_numbers,node_groundedness,node_judge_scoring toneMint
class node_provider_registry,node_provider_base,node_gemini,node_openai,node_grok,node_openrouter,node_pricing toneRose
class node_law_db,node_ingest_hy,node_ingest_en,node_article_data,node_article_data_en,node_loader,node_user,node_provider_services toneIndigo
```

## Components

### User interface

- [Web interface](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/static/index.html): `static/index.html`
- [Browser client](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/static/app.js): `static/app.js`

### API workflows

- [FastAPI server](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/app.py): `app.py`
- [Ask workflow](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/app.py): `app.py`
- [Benchmark runner](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/app.py): `app.py`
- [Question set](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/benchmark/questions.json): `benchmark/questions.json`

### Retrieval and scoring

- [Hybrid retrieval](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/retriever.py): `rag/retriever.py`
- [Query embeddings](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/retriever.py): `rag/retriever.py`
- [Postgres search](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/pgvector_store.py): `rag/pgvector_store.py`
- [Context and prompt](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/pipeline.py): `rag/pipeline.py`
- [Citation parsing](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/article_numbers.py): `rag/article_numbers.py`
- [Citation checking](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/pipeline.py): `rag/pipeline.py`
- [Judge scoring](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/rag/scoring.py): `rag/scoring.py`

### LLM providers

- [Provider registry](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/__init__.py): `providers/__init__.py`
- [Provider interface](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/base.py): `providers/base.py`
- [Gemini adapter](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/gemini_provider.py): `providers/gemini_provider.py`
- [OpenAI adapter](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/openai_provider.py): `providers/openai_provider.py`
- [Grok adapter](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/grok_provider.py): `providers/grok_provider.py`
- [OpenRouter adapter](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/openrouter_provider.py): `providers/openrouter_provider.py`
- [Cost estimates](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/providers/pricing.py): `providers/pricing.py`

### Law corpus

- [Law chunk store](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/db/schema.sql): `db/schema.sql`
- [Armenian ingestion](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/ingest.py): `data/ingest.py`
- [English ingestion](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/ingest_en.py): `data/ingest_en.py`
- [Pre-ingested articles](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/articles.json): `data/articles.json`
- [English articles](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/articles_en.json): `data/articles_en.json`
- [Embedding loader](https://github.com/muradyanhaykaz05-blip/electronic-comms-law-qa/blob/main/data/load_to_pgvector.py): `data/load_to_pgvector.py`

### Other components

- **Questioner**
- **LLM services**

## Connections

- Questioner → Browser client: asks (evidence: `README.md`)
- Browser client → FastAPI server: calls API (evidence: `README.md`)
- FastAPI server → Web interface: serves (evidence: `README.md`)
- FastAPI server → Ask workflow: routes ask (evidence: `app.py`)
- FastAPI server → Benchmark runner: routes benchmark (evidence: `app.py`)
- Ask workflow → Hybrid retrieval: builds context (evidence: `app.py`)
- Hybrid retrieval → Query embeddings: encodes query (evidence: `rag/retriever.py`)
- Hybrid retrieval → Postgres search: searches (evidence: `rag/retriever.py`)
- Postgres search → Law chunk store: queries (evidence: `rag/pgvector_store.py`)
- Ask workflow → Context and prompt: builds prompt (evidence: `app.py`)
- Context and prompt → Hybrid retrieval: retrieves chunks (evidence: `rag/pipeline.py`)
- Ask workflow → Provider registry: selects provider (evidence: `app.py`)
- Provider registry → Gemini adapter: configures (evidence: `providers/__init__.py`)
- Provider registry → OpenAI adapter: configures (evidence: `providers/__init__.py`)
- Provider registry → Grok adapter: configures (evidence: `providers/__init__.py`)
- Provider registry → OpenRouter adapter: configures (evidence: `providers/__init__.py`)
- Gemini adapter → Provider interface: implements (evidence: `providers/gemini_provider.py`)
- Grok adapter → Provider interface: extends (evidence: `providers/grok_provider.py`)
- OpenRouter adapter → Provider interface: extends (evidence: `providers/openrouter_provider.py`)
- OpenAI adapter → Provider interface: implements (evidence: `providers/base.py`)
- Ask workflow → Citation checking: checks citations (evidence: `app.py`)
- Citation checking → Citation parsing: parses numbers (evidence: `rag/pipeline.py`)
- Benchmark runner → Question set: loads questions (evidence: `README.md`)
- Benchmark runner → Hybrid retrieval: builds contexts (evidence: `app.py`)
- Benchmark runner → Judge scoring: scores answers (evidence: `app.py`)
- Judge scoring → Provider interface: calls judge (evidence: `rag/scoring.py`)
- Benchmark runner → Cost estimates: estimates cost (evidence: `README.md`)
- Gemini adapter → LLM services: streams responses (evidence: `providers/gemini_provider.py`)
- Grok adapter → LLM services: calls API (evidence: `providers/grok_provider.py`)
- OpenRouter adapter → LLM services: calls API (evidence: `providers/openrouter_provider.py`)
- Armenian ingestion → Pre-ingested articles: produces
- English ingestion → English articles: produces
- Pre-ingested articles → Embedding loader: loads chunks (evidence: `README.md`)
- English articles → Embedding loader: loads chunks (evidence: `README.md`)
- Embedding loader → Law chunk store: embeds and upserts (evidence: `README.md`)
