# thej-tech/ripple-effect architecture

> Architecture diagram of the GitHub repository thej-tech/ripple-effect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thej-tech/ripple-effect
- Repository: https://github.com/thej-tech/ripple-effect

## Overview

Ripple Effect is a workspace-based application for modeling dependencies and tracing disruption impact. Users build a system, assess and approve dependency weights, create an event and triggers, run an analysis, inspect persisted paths and history, and optionally explain or compare scenario results. The graph includes the documented dashboard and scenario workflow as well as the sampled backend analysis layers. Some frontend-to-backend and optional Ollama connections are documented in the README rather than shown in sampled call sites.

Main entry points: [`backend/app/api.py`](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/api.py) (HTTP API), [`backend/app/models.py`](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/models.py) (Domain records), [`frontend/src/App.tsx`](https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/App.tsx) (Workspace UI), [`backend/app/analysis_service.py`](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/analysis_service.py) (Analysis orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Workspace interface"]
  node_app["Workspace UI<br/>[App.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_impact_graph["Impact graph<br/>[ImpactGraph.tsx]"]
  node_scenario_ui["Scenario workspace"]
end

subgraph group_api["API and access"]
  node_api_server["HTTP API<br/>[api.py]"]
  node_app_server["Application entry<br/>[main.py]"]
  node_auth["Membership authorization<br/>[auth.py]"]
end

subgraph group_domain["Model and analysis"]
  node_workspace_data["Workspace management<br/>[services.py]"]
  node_analysis_service["Analysis orchestration"]
  node_engine["Impact engine<br/>[engine.py]"]
  node_scenario_service["Scenario service"]
  node_ai_service["AI assessment and explanations<br/>[ai_service.py]"]
end

subgraph group_persistence["Persistence and AI"]
  node_models["Domain records<br/>[models.py]"]
  node_repositories["Data repositories<br/>[repositories.py]"]
  node_database[("Relational database<br/>[database.py]")]
end

node_user(("Team user"))
node_ollama{{"Ollama service"}}

node_user -->|"uses"| node_app
node_app -->|"requests through"| node_client
node_app -->|"renders"| node_scenario_ui
node_app -.->|"shows results"| node_impact_graph
node_client -->|"calls"| node_api_server
node_app_server -->|"mounts routes"| node_api_server
node_api_server -->|"authorizes requests"| node_auth
node_api_server -->|"handles workspace changes"| node_workspace_data
node_api_server -->|"runs analysis"| node_analysis_service
node_api_server -->|"handles scenarios"| node_scenario_service
node_api_server -->|"requests AI output"| node_ai_service
node_analysis_service -->|"calculates impact"| node_engine
node_scenario_service -->|"creates scenario runs"| node_analysis_service
node_scenario_ui -->|"loads and saves"| node_client
node_workspace_data -->|"uses"| node_repositories
node_workspace_data -->|"updates records"| node_models
node_analysis_service -->|"persists runs"| node_models
node_scenario_service -->|"stores scenarios"| node_models
node_auth -->|"checks membership"| node_models
node_models -->|"uses ORM base"| node_database
node_ai_service -.->|"requests assessment"| node_ollama
node_user -->|"compares scenarios"| node_scenario_ui

click node_app "https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/App.tsx"
click node_client "https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/api.ts"
click node_impact_graph "https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/ImpactGraph.tsx"
click node_scenario_ui "https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/ScenarioWorkspace.tsx"
click node_api_server "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/api.py"
click node_app_server "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/main.py"
click node_auth "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/auth.py"
click node_workspace_data "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/services.py"
click node_analysis_service "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/analysis_service.py"
click node_engine "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/engine.py"
click node_scenario_service "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/scenario_service.py"
click node_ai_service "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/ai_service.py"
click node_models "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/models.py"
click node_repositories "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/repositories.py"
click node_database "https://github.com/thej-tech/ripple-effect/blob/main/backend/app/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_client,node_impact_graph,node_scenario_ui,node_user toneBlue
class node_api_server,node_app_server,node_auth toneAmber
class node_workspace_data,node_analysis_service,node_engine,node_scenario_service,node_ai_service toneMint
class node_models,node_repositories,node_database toneRose
class node_ollama toneIndigo
```

## Components

### Workspace interface

- [Workspace UI](https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Impact graph](https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/ImpactGraph.tsx): `frontend/src/ImpactGraph.tsx`
- [Scenario workspace](https://github.com/thej-tech/ripple-effect/blob/main/frontend/src/ScenarioWorkspace.tsx): `frontend/src/ScenarioWorkspace.tsx`

### API and access

- [HTTP API](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/api.py): `backend/app/api.py`
- [Application entry](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/main.py): `backend/app/main.py`
- [Membership authorization](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/auth.py): `backend/app/auth.py`

### Model and analysis

- [Workspace management](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/services.py): `backend/app/services.py`
- [Analysis orchestration](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/analysis_service.py): `backend/app/analysis_service.py`
- [Impact engine](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/engine.py): `backend/app/engine.py`
- [Scenario service](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/scenario_service.py): `backend/app/scenario_service.py`
- [AI assessment and explanations](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/ai_service.py): `backend/app/ai_service.py`

### Persistence and AI

- [Domain records](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/models.py): `backend/app/models.py`
- [Data repositories](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/repositories.py): `backend/app/repositories.py`
- [Relational database](https://github.com/thej-tech/ripple-effect/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Team user**
- **Ollama service**

## Connections

- Team user → Workspace UI: uses (evidence: `README.md`)
- Workspace UI → API client: requests through (evidence: `frontend/src/App.tsx`)
- Workspace UI → Scenario workspace: renders (evidence: `frontend/src/App.tsx`)
- Workspace UI → Impact graph: shows results
- API client → HTTP API: calls (evidence: `README.md`)
- Application entry → HTTP API: mounts routes (evidence: `backend/app/main.py`)
- HTTP API → Membership authorization: authorizes requests (evidence: `backend/app/api.py`)
- HTTP API → Workspace management: handles workspace changes (evidence: `backend/app/api.py`)
- HTTP API → Analysis orchestration: runs analysis (evidence: `backend/app/api.py`)
- HTTP API → Scenario service: handles scenarios (evidence: `backend/app/api.py`)
- HTTP API → AI assessment and explanations: requests AI output (evidence: `backend/app/api.py`)
- Analysis orchestration → Impact engine: calculates impact (evidence: `backend/app/analysis_service.py`)
- Scenario service → Analysis orchestration: creates scenario runs (evidence: `backend/app/scenario_service.py`)
- Scenario workspace → API client: loads and saves (evidence: `frontend/src/ScenarioWorkspace.tsx`)
- Workspace management → Data repositories: uses (evidence: `backend/app/services.py`)
- Workspace management → Domain records: updates records (evidence: `backend/app/services.py`)
- Analysis orchestration → Domain records: persists runs (evidence: `backend/app/analysis_service.py`)
- Scenario service → Domain records: stores scenarios (evidence: `backend/app/scenario_service.py`)
- Membership authorization → Domain records: checks membership (evidence: `backend/app/auth.py`)
- Domain records → Relational database: uses ORM base (evidence: `backend/app/models.py`)
- AI assessment and explanations → Ollama service: requests assessment (evidence: `README.md`)
- Team user → Scenario workspace: compares scenarios (evidence: `README.md`)
