# abtvenkat/ds-modelforge architecture

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

- Interactive diagram: https://gitdiagram.com/abtvenkat/ds-modelforge
- Repository: https://github.com/abtvenkat/ds-modelforge

## Overview

DS-ModelForge is a web application for designing SAP Datasphere data models from user requirements. Users configure a Datasphere connection, scan and explore its catalog, submit a modeling request, review generated views and lineage on the canvas, and export artifacts. The backend exposes API routes and a run/agent workflow, with persistent run and catalog state. The file tree and source index support these major stages, but most agent and builder implementations were not excerpted, so their internal calls are not expanded.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/api/client.ts) (API client), [`backend/app/main.py`](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/App.tsx`](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/App.tsx) (Application shell), [`backend/app/api/v1/catalog.py`](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/catalog.py) (Catalog routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Application shell<br/>[App.tsx]"]
  node_connections_ui["Connections"]
  node_catalog_ui["Catalog browser<br/>[CatalogPage.tsx]"]
  node_requirement_ui["Requirement chat"]
  node_canvas["Model canvas"]
  node_playbook_modal["Playbook review"]
  node_export_ui["Export page<br/>[ExportPage.tsx]"]
  node_client_api["API client<br/>[client.ts]"]
  node_state["UI state<br/>[useStore.ts]"]
end

subgraph group_api["API and workflow"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth["Authentication routes<br/>[auth_routes.py]"]
  node_connections_api["Connection routes<br/>[connections.py]"]
  node_catalog_api["Catalog routes<br/>[catalog.py]"]
  node_chat_api["Chat routes<br/>[chat.py]"]
  node_runs_api["Run routes<br/>[runs.py]"]
  node_views_api["View routes<br/>[views.py]"]
  node_export_api["Export routes<br/>[export.py]"]
  node_ws_api["Run updates<br/>[websocket.py]"]
end

subgraph group_modeling["Modeling services"]
  node_agent["Agent graph<br/>[graph.py]"]
  node_agent_nodes["Agent steps<br/>[nodes.py]"]
  node_llm["LLM service<br/>[llm.py]"]
  node_profiler["Catalog profiler<br/>[profiler.py]"]
  node_playbook["Playbook builder"]
  node_validator["Model validator<br/>[validator.py]"]
  node_renderer["Artifact renderer"]
  node_export_service["Export service<br/>[export_service.py]"]
end

subgraph group_persistence["Persistence"]
  node_models["Catalog and run records<br/>[catalog.py]"]
  node_run_model["Run and view specs<br/>[run.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
end

subgraph group_integration["External systems"]
  node_reader["Datasphere reader<br/>[reader.py]"]
end

node_user(("Modeler"))
node_datasphere{{"SAP Datasphere"}}
node_llm_provider{{"LLM provider"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_connections_ui
node_app -->|"routes to"| node_catalog_ui
node_app -->|"routes to"| node_requirement_ui
node_app -->|"routes to"| node_canvas
node_app -->|"routes to"| node_export_ui
node_app -->|"reads"| node_state
node_connections_ui -->|"requests"| node_client_api
node_catalog_ui -->|"requests"| node_client_api
node_requirement_ui -->|"submits request"| node_client_api
node_canvas -->|"requests data"| node_client_api
node_canvas -->|"opens"| node_playbook_modal
node_canvas -->|"reads and updates"| node_state
node_playbook_modal -->|"requests"| node_client_api
node_export_ui -->|"requests export"| node_client_api
node_client_api -->|"calls"| node_connections_api
node_client_api -->|"calls"| node_catalog_api
node_client_api -->|"calls"| node_runs_api
node_client_api -->|"calls"| node_export_api
node_api_app -->|"mounts"| node_auth
node_api_app -->|"mounts"| node_connections_api
node_api_app -->|"mounts"| node_catalog_api
node_api_app -->|"mounts"| node_chat_api
node_api_app -->|"mounts"| node_runs_api
node_api_app -->|"mounts"| node_views_api
node_api_app -->|"mounts"| node_export_api
node_api_app -->|"mounts"| node_ws_api
node_catalog_api -->|"reads source catalog"| node_reader
node_catalog_api -->|"profiles data"| node_profiler
node_catalog_api -->|"queries and stores"| node_models
node_reader -.->|"reads remotely"| node_datasphere
node_runs_api -->|"starts workflow"| node_agent
node_runs_api -->|"builds playbook"| node_playbook
node_runs_api -->|"persists run state"| node_run_model
node_chat_api -->|"sends prompt"| node_llm
node_chat_api -->|"validates model"| node_validator
node_agent -.->|"dispatches steps"| node_agent_nodes
node_llm -.->|"requests completions"| node_llm_provider
node_renderer -->|"reads view specs"| node_run_model
node_export_api -.->|"delegates export"| node_export_service
node_export_service -.->|"adapts artifacts"| node_datasphere
node_database -.->|"stores records"| node_models
node_database -.->|"stores run state"| node_run_model

click node_app "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/App.tsx"
click node_connections_ui "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/ConnectionsPage.tsx"
click node_catalog_ui "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/CatalogPage.tsx"
click node_requirement_ui "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/ChatRequirementPage.tsx"
click node_canvas "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/components/canvas/DatasphereCanvas.tsx"
click node_playbook_modal "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/components/canvas/DataspherePlaybookModal.tsx"
click node_export_ui "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/ExportPage.tsx"
click node_client_api "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/api/client.ts"
click node_state "https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/store/useStore.ts"
click node_api_app "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/main.py"
click node_auth "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/auth_routes.py"
click node_connections_api "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/connections.py"
click node_catalog_api "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/catalog.py"
click node_chat_api "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/chat.py"
click node_runs_api "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/runs.py"
click node_views_api "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/views.py"
click node_export_api "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/export.py"
click node_ws_api "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/websocket.py"
click node_agent "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/agent/graph.py"
click node_agent_nodes "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/agent/nodes.py"
click node_llm "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/agent/llm.py"
click node_reader "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/ds/reader.py"
click node_profiler "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/ds/profiler.py"
click node_playbook "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/playbook_builder.py"
click node_validator "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/validator.py"
click node_renderer "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/renderer_service.py"
click node_export_service "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/export_service.py"
click node_models "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/models/catalog.py"
click node_run_model "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/models/run.py"
click node_database "https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/core/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_connections_ui,node_catalog_ui,node_requirement_ui,node_canvas,node_playbook_modal,node_export_ui,node_client_api,node_state toneBlue
class node_api_app,node_auth,node_connections_api,node_catalog_api,node_chat_api,node_runs_api,node_views_api,node_export_api,node_ws_api toneAmber
class node_agent,node_agent_nodes,node_llm,node_profiler,node_playbook,node_validator,node_renderer,node_export_service toneMint
class node_models,node_run_model,node_database toneRose
class node_reader,node_user,node_datasphere,node_llm_provider toneIndigo
```

## Components

### Web client

- [Application shell](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Connections](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/ConnectionsPage.tsx): `frontend/src/pages/ConnectionsPage.tsx`
- [Catalog browser](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/CatalogPage.tsx): `frontend/src/pages/CatalogPage.tsx`
- [Requirement chat](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/ChatRequirementPage.tsx): `frontend/src/pages/ChatRequirementPage.tsx`
- [Model canvas](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/components/canvas/DatasphereCanvas.tsx): `frontend/src/components/canvas/DatasphereCanvas.tsx`
- [Playbook review](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/components/canvas/DataspherePlaybookModal.tsx): `frontend/src/components/canvas/DataspherePlaybookModal.tsx`
- [Export page](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/pages/ExportPage.tsx): `frontend/src/pages/ExportPage.tsx`
- [API client](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [UI state](https://github.com/abtvenkat/ds-modelforge/blob/main/frontend/src/store/useStore.ts): `frontend/src/store/useStore.ts`

### API and workflow

- [FastAPI app](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/auth_routes.py): `backend/app/api/v1/auth_routes.py`
- [Connection routes](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/connections.py): `backend/app/api/v1/connections.py`
- [Catalog routes](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/catalog.py): `backend/app/api/v1/catalog.py`
- [Chat routes](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/chat.py): `backend/app/api/v1/chat.py`
- [Run routes](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/runs.py): `backend/app/api/v1/runs.py`
- [View routes](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/views.py): `backend/app/api/v1/views.py`
- [Export routes](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/export.py): `backend/app/api/v1/export.py`
- [Run updates](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/api/v1/websocket.py): `backend/app/api/v1/websocket.py`

### Modeling services

- [Agent graph](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/agent/graph.py): `backend/app/agent/graph.py`
- [Agent steps](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/agent/nodes.py): `backend/app/agent/nodes.py`
- [LLM service](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/agent/llm.py): `backend/app/agent/llm.py`
- [Catalog profiler](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/ds/profiler.py): `backend/app/ds/profiler.py`
- [Playbook builder](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/playbook_builder.py): `backend/app/services/playbook_builder.py`
- [Model validator](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/validator.py): `backend/app/services/validator.py`
- [Artifact renderer](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/renderer_service.py): `backend/app/services/renderer_service.py`
- [Export service](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/services/export_service.py): `backend/app/services/export_service.py`

### Persistence

- [Catalog and run records](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/models/catalog.py): `backend/app/models/catalog.py`
- [Run and view specs](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/models/run.py): `backend/app/models/run.py`
- [PostgreSQL](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### External systems

- [Datasphere reader](https://github.com/abtvenkat/ds-modelforge/blob/main/backend/app/ds/reader.py): `backend/app/ds/reader.py`

### Other components

- **Modeler**
- **SAP Datasphere**
- **LLM provider**

## Connections

- Modeler → Application shell: uses (evidence: `frontend/src/App.tsx`)
- Application shell → Connections: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Catalog browser: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Requirement chat: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Model canvas: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → Export page: routes to (evidence: `frontend/src/App.tsx`)
- Application shell → UI state: reads (evidence: `frontend/src/App.tsx`)
- Connections → API client: requests (evidence: `frontend/src/pages/ConnectionsPage.tsx`)
- Catalog browser → API client: requests (evidence: `frontend/src/pages/CatalogPage.tsx`)
- Requirement chat → API client: submits request (evidence: `frontend/src/pages/ChatRequirementPage.tsx`)
- Model canvas → API client: requests data (evidence: `frontend/src/components/canvas/DatasphereCanvas.tsx`)
- Model canvas → Playbook review: opens (evidence: `frontend/src/components/canvas/DatasphereCanvas.tsx`)
- Model canvas → UI state: reads and updates (evidence: `frontend/src/components/canvas/DatasphereCanvas.tsx`)
- Playbook review → API client: requests (evidence: `frontend/src/components/canvas/DataspherePlaybookModal.tsx`)
- Export page → API client: requests export (evidence: `frontend/src/pages/ExportPage.tsx`)
- API client → Connection routes: calls (evidence: `frontend/src/api/client.ts`)
- API client → Catalog routes: calls (evidence: `frontend/src/api/client.ts`)
- API client → Run routes: calls (evidence: `frontend/src/api/client.ts`)
- API client → Export routes: calls (evidence: `frontend/src/api/client.ts`)
- FastAPI app → Authentication routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Connection routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Catalog routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Chat routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Run routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → View routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Export routes: mounts (evidence: `backend/app/main.py`)
- FastAPI app → Run updates: mounts (evidence: `backend/app/main.py`)
- Catalog routes → Datasphere reader: reads source catalog (evidence: `backend/app/api/v1/catalog.py`)
- Catalog routes → Catalog profiler: profiles data (evidence: `backend/app/api/v1/catalog.py`)
- Catalog routes → Catalog and run records: queries and stores (evidence: `backend/app/api/v1/catalog.py`)
- Datasphere reader → SAP Datasphere: reads remotely (evidence: `backend/app/ds/reader.py`)
- Run routes → Agent graph: starts workflow (evidence: `backend/app/api/v1/runs.py`)
- Run routes → Playbook builder: builds playbook (evidence: `backend/app/api/v1/runs.py`)
- Run routes → Run and view specs: persists run state (evidence: `backend/app/api/v1/runs.py`)
- Chat routes → LLM service: sends prompt (evidence: `backend/app/api/v1/chat.py`)
- Chat routes → Model validator: validates model (evidence: `backend/app/api/v1/chat.py`)
- Agent graph → Agent steps: dispatches steps
- LLM service → LLM provider: requests completions
- Artifact renderer → Run and view specs: reads view specs (evidence: `backend/app/services/renderer_service.py`)
- Export routes → Export service: delegates export
- Export service → SAP Datasphere: adapts artifacts (evidence: `backend/app/services/export_service.py`)
- PostgreSQL → Catalog and run records: stores records (evidence: `backend/app/models/catalog.py`)
- PostgreSQL → Run and view specs: stores run state (evidence: `backend/app/models/run.py`)
