# yashpadhye17/faultline architecture

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

- Interactive diagram: https://gitdiagram.com/yashpadhye17/faultline
- Repository: https://github.com/yashpadhye17/faultline

## Overview

EIRC is a NASA-grounded engineering copilot with four user-facing workflows: root-cause analysis, maintenance troubleshooting, engineering comparison, and research. Requests enter through the FastAPI router and are handled by feature services that retrieve evidence, construct prompts, invoke a language model, and return structured, cited results. Shared retrieval combines a FAISS/HNSW vector store with BM25 and reranking; uploads can contribute session-specific documents. The README also documents evaluation through the UI and APIs. Some wiring is supported only by the source index or README, so unsampled relationships are omitted rather than inferred.

Main entry points: [`api/routers.py`](https://github.com/yashpadhye17/faultline/blob/main/api/routers.py) (FastAPI routes), [`utils/base_feature_service.py`](https://github.com/yashpadhye17/faultline/blob/main/utils/base_feature_service.py) (Feature orchestration), [`utils/retriever_service.py`](https://github.com/yashpadhye17/faultline/blob/main/utils/retriever_service.py) (Hybrid retrieval), [`utils/evaluation_runner.py`](https://github.com/yashpadhye17/faultline/blob/main/utils/evaluation_runner.py) (Evaluation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and contracts"]
  node_api["FastAPI routes<br/>[routers.py]"]
  node_contracts["Request and result models<br/>[models.py]"]
end

subgraph group_features["Copilot workflows"]
  node_rca["Root cause analysis<br/>[service.py]"]
  node_maintenance["Maintenance troubleshooting<br/>[service.py]"]
  node_comparison["Engineering comparison<br/>[service.py]"]
  node_research["NASA research<br/>[service.py]"]
end

subgraph group_shared["Shared intelligence"]
  node_upload["Session uploads<br/>[upload_context.py]"]
  node_base["Feature orchestration"]
  node_retriever["Hybrid retrieval"]
  node_vectorstore[("FAISS HNSW store")]
  node_bm25[("BM25 index<br/>[bm25_index.py]")]
  node_reranker["Result reranking<br/>[reranker.py]"]
  node_pipeline["Document processing"]
  node_prompts["Prompt management<br/>[prompt_manager.py]"]
  node_models["Model loading<br/>[model_loader.py]"]
  node_citation["Citation enforcement"]
end

subgraph group_ops["Evaluation and telemetry"]
  node_telemetry["Request telemetry<br/>[telemetry.py]"]
  node_evaluation["Evaluation runner"]
  node_artifacts[("Evaluation artifacts")]
end

node_user(("Engineer"))
node_llm{{"Groq language model"}}

node_user -->|"submits requests"| node_api
node_api -->|"validates payloads"| node_contracts
node_api -->|"stores uploads"| node_upload
node_api -->|"routes RCA"| node_rca
node_api -->|"routes chat"| node_maintenance
node_api -->|"routes comparison"| node_comparison
node_api -->|"routes research"| node_research
node_rca -->|"retrieves evidence"| node_retriever
node_maintenance -->|"retrieves evidence"| node_retriever
node_comparison -->|"retrieves evidence"| node_retriever
node_research -->|"retrieves evidence"| node_retriever
node_rca -->|"renders prompt"| node_prompts
node_maintenance -->|"renders prompt"| node_prompts
node_comparison -->|"renders prompt"| node_prompts
node_research -->|"renders prompt"| node_prompts
node_rca -->|"inherits orchestration"| node_base
node_maintenance -->|"inherits orchestration"| node_base
node_comparison -->|"inherits orchestration"| node_base
node_research -->|"inherits orchestration"| node_base
node_base -->|"loads models"| node_models
node_base -->|"initializes manager"| node_upload
node_base -->|"records requests"| node_telemetry
node_base -->|"enforces citations"| node_citation
node_base -->|"invokes model"| node_llm
node_retriever -->|"searches index"| node_vectorstore
node_retriever -->|"reranks hits"| node_reranker
node_vectorstore -->|"queries sparse index"| node_bm25
node_vectorstore -->|"chunks corpus"| node_pipeline
node_vectorstore -->|"embeds documents"| node_models
node_api -->|"starts evaluation"| node_evaluation
node_api -->|"lists evaluation runs"| node_artifacts
node_evaluation -->|"evaluates feature"| node_rca
node_evaluation -->|"evaluates feature"| node_maintenance
node_evaluation -->|"evaluates feature"| node_comparison
node_evaluation -->|"evaluates feature"| node_research

click node_api "https://github.com/yashpadhye17/faultline/blob/main/api/routers.py"
click node_contracts "https://github.com/yashpadhye17/faultline/blob/main/models/models.py"
click node_upload "https://github.com/yashpadhye17/faultline/blob/main/utils/upload_context.py"
click node_rca "https://github.com/yashpadhye17/faultline/blob/main/src/document_analyze/service.py"
click node_maintenance "https://github.com/yashpadhye17/faultline/blob/main/src/single_docchat/service.py"
click node_comparison "https://github.com/yashpadhye17/faultline/blob/main/src/document_comparison/service.py"
click node_research "https://github.com/yashpadhye17/faultline/blob/main/src/multidoc_chat/service.py"
click node_base "https://github.com/yashpadhye17/faultline/blob/main/utils/base_feature_service.py"
click node_retriever "https://github.com/yashpadhye17/faultline/blob/main/utils/retriever_service.py"
click node_vectorstore "https://github.com/yashpadhye17/faultline/blob/main/utils/vectorstore_manager.py"
click node_bm25 "https://github.com/yashpadhye17/faultline/blob/main/utils/bm25_index.py"
click node_reranker "https://github.com/yashpadhye17/faultline/blob/main/utils/reranker.py"
click node_pipeline "https://github.com/yashpadhye17/faultline/blob/main/utils/document_pipeline.py"
click node_prompts "https://github.com/yashpadhye17/faultline/blob/main/utils/prompt_manager.py"
click node_models "https://github.com/yashpadhye17/faultline/blob/main/utils/model_loader.py"
click node_citation "https://github.com/yashpadhye17/faultline/blob/main/utils/citation_enforcer.py"
click node_telemetry "https://github.com/yashpadhye17/faultline/blob/main/utils/telemetry.py"
click node_evaluation "https://github.com/yashpadhye17/faultline/blob/main/utils/evaluation_runner.py"
click node_artifacts "https://github.com/yashpadhye17/faultline/blob/main/utils/evaluation_artifacts.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_api,node_contracts toneBlue
class node_rca,node_maintenance,node_comparison,node_research toneAmber
class node_upload,node_base,node_retriever,node_vectorstore,node_bm25,node_reranker,node_pipeline,node_prompts,node_models,node_citation toneMint
class node_telemetry,node_evaluation,node_artifacts toneRose
class node_user,node_llm toneIndigo
```

## Components

### API and contracts

- [FastAPI routes](https://github.com/yashpadhye17/faultline/blob/main/api/routers.py): `api/routers.py`
- [Request and result models](https://github.com/yashpadhye17/faultline/blob/main/models/models.py): `models/models.py`

### Copilot workflows

- [Root cause analysis](https://github.com/yashpadhye17/faultline/blob/main/src/document_analyze/service.py): `src/document_analyze/service.py`
- [Maintenance troubleshooting](https://github.com/yashpadhye17/faultline/blob/main/src/single_docchat/service.py): `src/single_docchat/service.py`
- [Engineering comparison](https://github.com/yashpadhye17/faultline/blob/main/src/document_comparison/service.py): `src/document_comparison/service.py`
- [NASA research](https://github.com/yashpadhye17/faultline/blob/main/src/multidoc_chat/service.py): `src/multidoc_chat/service.py`

### Shared intelligence

- [Session uploads](https://github.com/yashpadhye17/faultline/blob/main/utils/upload_context.py): `utils/upload_context.py`
- [Feature orchestration](https://github.com/yashpadhye17/faultline/blob/main/utils/base_feature_service.py): `utils/base_feature_service.py`
- [Hybrid retrieval](https://github.com/yashpadhye17/faultline/blob/main/utils/retriever_service.py): `utils/retriever_service.py`
- [FAISS HNSW store](https://github.com/yashpadhye17/faultline/blob/main/utils/vectorstore_manager.py): `utils/vectorstore_manager.py`
- [BM25 index](https://github.com/yashpadhye17/faultline/blob/main/utils/bm25_index.py): `utils/bm25_index.py`
- [Result reranking](https://github.com/yashpadhye17/faultline/blob/main/utils/reranker.py): `utils/reranker.py`
- [Document processing](https://github.com/yashpadhye17/faultline/blob/main/utils/document_pipeline.py): `utils/document_pipeline.py`
- [Prompt management](https://github.com/yashpadhye17/faultline/blob/main/utils/prompt_manager.py): `utils/prompt_manager.py`
- [Model loading](https://github.com/yashpadhye17/faultline/blob/main/utils/model_loader.py): `utils/model_loader.py`
- [Citation enforcement](https://github.com/yashpadhye17/faultline/blob/main/utils/citation_enforcer.py): `utils/citation_enforcer.py`

### Evaluation and telemetry

- [Request telemetry](https://github.com/yashpadhye17/faultline/blob/main/utils/telemetry.py): `utils/telemetry.py`
- [Evaluation runner](https://github.com/yashpadhye17/faultline/blob/main/utils/evaluation_runner.py): `utils/evaluation_runner.py`
- [Evaluation artifacts](https://github.com/yashpadhye17/faultline/blob/main/utils/evaluation_artifacts.py): `utils/evaluation_artifacts.py`

### Other components

- **Engineer**
- **Groq language model**

## Connections

- Engineer → FastAPI routes: submits requests (evidence: `README.md`)
- FastAPI routes → Request and result models: validates payloads (evidence: `api/routers.py`)
- FastAPI routes → Session uploads: stores uploads (evidence: `api/routers.py`)
- FastAPI routes → Root cause analysis: routes RCA (evidence: `api/routers.py`)
- FastAPI routes → Maintenance troubleshooting: routes chat (evidence: `api/routers.py`)
- FastAPI routes → Engineering comparison: routes comparison (evidence: `api/routers.py`)
- FastAPI routes → NASA research: routes research (evidence: `api/routers.py`)
- Root cause analysis → Hybrid retrieval: retrieves evidence (evidence: `src/document_analyze/service.py`)
- Maintenance troubleshooting → Hybrid retrieval: retrieves evidence (evidence: `src/single_docchat/service.py`)
- Engineering comparison → Hybrid retrieval: retrieves evidence (evidence: `src/document_comparison/service.py`)
- NASA research → Hybrid retrieval: retrieves evidence (evidence: `src/multidoc_chat/service.py`)
- Root cause analysis → Prompt management: renders prompt (evidence: `src/document_analyze/service.py`)
- Maintenance troubleshooting → Prompt management: renders prompt (evidence: `src/single_docchat/service.py`)
- Engineering comparison → Prompt management: renders prompt (evidence: `src/document_comparison/service.py`)
- NASA research → Prompt management: renders prompt (evidence: `src/multidoc_chat/service.py`)
- Root cause analysis → Feature orchestration: inherits orchestration (evidence: `src/document_analyze/service.py`)
- Maintenance troubleshooting → Feature orchestration: inherits orchestration (evidence: `src/single_docchat/service.py`)
- Engineering comparison → Feature orchestration: inherits orchestration (evidence: `src/document_comparison/service.py`)
- NASA research → Feature orchestration: inherits orchestration (evidence: `src/multidoc_chat/service.py`)
- Feature orchestration → Model loading: loads models (evidence: `utils/base_feature_service.py`)
- Feature orchestration → Session uploads: initializes manager (evidence: `utils/base_feature_service.py`)
- Feature orchestration → Request telemetry: records requests (evidence: `utils/base_feature_service.py`)
- Feature orchestration → Citation enforcement: enforces citations (evidence: `utils/base_feature_service.py`)
- Feature orchestration → Groq language model: invokes model (evidence: `utils/base_feature_service.py`)
- Hybrid retrieval → FAISS HNSW store: searches index (evidence: `utils/retriever_service.py`)
- Hybrid retrieval → Result reranking: reranks hits (evidence: `utils/retriever_service.py`)
- FAISS HNSW store → BM25 index: queries sparse index (evidence: `utils/vectorstore_manager.py`)
- FAISS HNSW store → Document processing: chunks corpus (evidence: `utils/vectorstore_manager.py`)
- FAISS HNSW store → Model loading: embeds documents (evidence: `utils/vectorstore_manager.py`)
- FastAPI routes → Evaluation runner: starts evaluation (evidence: `api/routers.py`)
- FastAPI routes → Evaluation artifacts: lists evaluation runs (evidence: `api/routers.py`)
- Evaluation runner → Root cause analysis: evaluates feature (evidence: `utils/evaluation_runner.py`)
- Evaluation runner → Maintenance troubleshooting: evaluates feature (evidence: `utils/evaluation_runner.py`)
- Evaluation runner → Engineering comparison: evaluates feature (evidence: `utils/evaluation_runner.py`)
- Evaluation runner → NASA research: evaluates feature (evidence: `utils/evaluation_runner.py`)
