# aleenagibi/ripple-business-change-intelligence architecture

> Architecture diagram of the GitHub repository aleenagibi/ripple-business-change-intelligence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aleenagibi/ripple-business-change-intelligence
- Repository: https://github.com/aleenagibi/ripple-business-change-intelligence

## Overview

Ripple is an enterprise change-impact platform: users upload organizational documents, then search or submit a requirement change to find potentially affected assets. Document processing extracts text, chunks it, identifies entities and relationships, and resolves duplicate mentions into canonical entities; retrieval and graph-based impact analysis combine evidence for results. The graph preserves README-documented NLP and knowledge-graph stages, while sampled source confirms key route-to-service and retrieval calls. Some internal processing links rely on the README because their service implementations were not sampled.

Main entry points: [`backend/app/services/retrieval_service.py`](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/retrieval_service.py) (Retrieval service), [`backend/app/services/impact_analysis_service.py`](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/impact_analysis_service.py) (Impact analysis), [`backend/app/services/document_service.py`](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/document_service.py) (Document service), [`backend/app/api/retrieval_routes.py`](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/api/retrieval_routes.py) (Retrieval routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App shell<br/>[App.tsx]"]
  node_documents_page["Documents page<br/>[DocumentsPage.tsx]"]
  node_impact_page["Impact page"]
  node_documents_api["Documents client<br/>[documents.ts]"]
  node_impact_api["Impact client<br/>[impact.ts]"]
end

subgraph group_api["HTTP API"]
  node_main["FastAPI app<br/>[main.py]"]
  node_document_routes["Document routes<br/>[document_routes.py]"]
  node_retrieval_routes["Retrieval routes"]
  node_auth_routes["Auth routes<br/>[auth_routes.py]"]
end

subgraph group_processing["Document intelligence"]
  node_document_service["Document service"]
  node_text_extraction["Text extraction"]
  node_chunk_service["Chunking<br/>[chunk_service.py]"]
  node_entity_extraction["Entity extraction"]
  node_relationship_extraction["Relationship extraction"]
  node_canonical["Canonical resolution"]
end

subgraph group_analysis["Retrieval and impact"]
  node_retrieval_service["Retrieval service"]
  node_tfidf["TF-IDF search<br/>[tfidf_engine.py]"]
  node_dense["Dense search<br/>[dense_engine.py]"]
  node_hybrid["Hybrid fusion<br/>[hybrid_engine.py]"]
  node_impact_service["Impact analysis"]
  node_impact_engine["Impact scoring"]
  node_knowledge_graph["Knowledge graph"]
end

subgraph group_storage["Persistence"]
  node_database[("Relational database<br/>[database.py]")]
end

node_user(("Organization user"))

node_user -->|"uses"| node_app
node_app -->|"shows"| node_documents_page
node_app -->|"shows"| node_impact_page
node_documents_page -->|"requests"| node_documents_api
node_impact_page -->|"requests"| node_impact_api
node_documents_api -->|"calls"| node_document_routes
node_impact_api -->|"calls"| node_retrieval_routes
node_main -->|"registers"| node_document_routes
node_main -->|"registers"| node_retrieval_routes
node_main -->|"registers"| node_auth_routes
node_document_routes -->|"calls"| node_document_service
node_document_service -->|"extracts text"| node_text_extraction
node_document_service -->|"chunks"| node_chunk_service
node_chunk_service -->|"extracts entities"| node_entity_extraction
node_chunk_service -->|"extracts relations"| node_relationship_extraction
node_canonical -->|"resolves mentions"| node_entity_extraction
node_retrieval_routes -->|"calls"| node_retrieval_service
node_retrieval_service -->|"searches"| node_tfidf
node_retrieval_service -->|"searches"| node_dense
node_retrieval_service -->|"fuses results"| node_hybrid
node_retrieval_routes -->|"calls"| node_impact_service
node_impact_service -->|"retrieves evidence"| node_retrieval_service
node_impact_service -->|"uses graph"| node_knowledge_graph
node_impact_service -->|"scores impact"| node_impact_engine
node_document_service -->|"persists records"| node_database
node_retrieval_service -->|"loads chunks"| node_database
node_impact_service -->|"loads entities"| node_database

click node_app "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/App.tsx"
click node_documents_page "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/pages/DocumentsPage.tsx"
click node_impact_page "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/pages/ImpactAnalysisPage.tsx"
click node_documents_api "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/api/documents.ts"
click node_impact_api "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/api/impact.ts"
click node_main "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/main.py"
click node_document_routes "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/api/document_routes.py"
click node_retrieval_routes "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/api/retrieval_routes.py"
click node_auth_routes "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/api/auth_routes.py"
click node_document_service "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/document_service.py"
click node_text_extraction "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/document_extraction_service.py"
click node_chunk_service "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/chunk_service.py"
click node_entity_extraction "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/entity_extraction_engine.py"
click node_relationship_extraction "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/relationship_extraction_engine.py"
click node_canonical "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/canonical_reconciliation_service.py"
click node_retrieval_service "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/retrieval_service.py"
click node_tfidf "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/tfidf_engine.py"
click node_dense "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/dense_engine.py"
click node_hybrid "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/hybrid_engine.py"
click node_impact_service "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/impact_analysis_service.py"
click node_impact_engine "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/impact_analysis_engine.py"
click node_knowledge_graph "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/knowledge_graph_service.py"
click node_database "https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/db/database.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_app,node_documents_page,node_impact_page,node_documents_api,node_impact_api,node_user toneBlue
class node_main,node_document_routes,node_retrieval_routes,node_auth_routes toneAmber
class node_document_service,node_text_extraction,node_chunk_service,node_entity_extraction,node_relationship_extraction,node_canonical toneMint
class node_retrieval_service,node_tfidf,node_dense,node_hybrid,node_impact_service,node_impact_engine,node_knowledge_graph toneRose
class node_database toneIndigo
```

## Components

### Web application

- [App shell](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Documents page](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/pages/DocumentsPage.tsx): `frontend/src/pages/DocumentsPage.tsx`
- [Impact page](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/pages/ImpactAnalysisPage.tsx): `frontend/src/pages/ImpactAnalysisPage.tsx`
- [Documents client](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/api/documents.ts): `frontend/src/api/documents.ts`
- [Impact client](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/frontend/src/api/impact.ts): `frontend/src/api/impact.ts`

### HTTP API

- [FastAPI app](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/main.py): `backend/app/main.py`
- [Document routes](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/api/document_routes.py): `backend/app/api/document_routes.py`
- [Retrieval routes](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/api/retrieval_routes.py): `backend/app/api/retrieval_routes.py`
- [Auth routes](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/api/auth_routes.py): `backend/app/api/auth_routes.py`

### Document intelligence

- [Document service](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/document_service.py): `backend/app/services/document_service.py`
- [Text extraction](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/document_extraction_service.py): `backend/app/services/document_extraction_service.py`
- [Chunking](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/chunk_service.py): `backend/app/services/chunk_service.py`
- [Entity extraction](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/entity_extraction_engine.py): `backend/app/engines/entity_extraction_engine.py`
- [Relationship extraction](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/relationship_extraction_engine.py): `backend/app/engines/relationship_extraction_engine.py`
- [Canonical resolution](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/canonical_reconciliation_service.py): `backend/app/services/canonical_reconciliation_service.py`

### Retrieval and impact

- [Retrieval service](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/retrieval_service.py): `backend/app/services/retrieval_service.py`
- [TF-IDF search](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/tfidf_engine.py): `backend/app/engines/tfidf_engine.py`
- [Dense search](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/dense_engine.py): `backend/app/engines/dense_engine.py`
- [Hybrid fusion](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/hybrid_engine.py): `backend/app/engines/hybrid_engine.py`
- [Impact analysis](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/impact_analysis_service.py): `backend/app/services/impact_analysis_service.py`
- [Impact scoring](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/engines/impact_analysis_engine.py): `backend/app/engines/impact_analysis_engine.py`
- [Knowledge graph](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/services/knowledge_graph_service.py): `backend/app/services/knowledge_graph_service.py`

### Persistence

- [Relational database](https://github.com/aleenagibi/ripple-business-change-intelligence/blob/main/backend/app/db/database.py): `backend/app/db/database.py`

### Other components

- **Organization user**

## Connections

- Organization user → App shell: uses
- App shell → Documents page: shows
- App shell → Impact page: shows
- Documents page → Documents client: requests
- Impact page → Impact client: requests
- Documents client → Document routes: calls
- Impact client → Retrieval routes: calls
- FastAPI app → Document routes: registers
- FastAPI app → Retrieval routes: registers
- FastAPI app → Auth routes: registers
- Document routes → Document service: calls
- Document service → Text extraction: extracts text
- Document service → Chunking: chunks
- Chunking → Entity extraction: extracts entities
- Chunking → Relationship extraction: extracts relations
- Canonical resolution → Entity extraction: resolves mentions
- Retrieval routes → Retrieval service: calls
- Retrieval service → TF-IDF search: searches
- Retrieval service → Dense search: searches
- Retrieval service → Hybrid fusion: fuses results
- Retrieval routes → Impact analysis: calls
- Impact analysis → Retrieval service: retrieves evidence
- Impact analysis → Knowledge graph: uses graph
- Impact analysis → Impact scoring: scores impact
- Document service → Relational database: persists records
- Retrieval service → Relational database: loads chunks
- Impact analysis → Relational database: loads entities