# ayushgadag/dbscope architecture

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

- Interactive diagram: https://gitdiagram.com/ayushgadag/dbscope
- Repository: https://github.com/ayushgadag/dbscope

## Overview

DBScope analyzes proposed schema changes without executing them: migration parsing, optional PostgreSQL metadata verification, static application-source ingestion and dependency tracing, followed by impact and risk assessment. Its FastAPI endpoints expose these capabilities. The React dashboard presents ten analysis views; the README describes its services as a mock-backed prototype with a future live-backend switch. Edges reflect the excerpts, SOURCE INDEX references, or README; frontend-to-backend integration is shown as optional because the prototype does not establish a complete live workflow.

Main entry points: [`backend/dbscope/api/main.py`](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/main.py) (FastAPI Application), [`backend/dbscope/analysis_service.py`](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/analysis_service.py) (Analysis Orchestrator), [`backend/dbscope/impact/service.py`](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/impact/service.py) (Impact Analysis), [`frontend/src/pages`](https://github.com/ayushgadag/dbscope/tree/main/frontend/src/pages) (Analysis Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_views["Analysis Views"]
  node_change_view["Analyze Change<br/>[AnalyzeChange.tsx]"]
  node_overview_view["Overview<br/>[Overview.tsx]"]
  node_dashboard_layout["Dashboard Layout"]
  node_migration_service["Migration Service"]
  node_scanner_service["Scanner Service<br/>[scannerService.ts]"]
  node_http_client["HTTP Client<br/>[api.ts]"]
end

subgraph group_api["REST API"]
  node_api_app["FastAPI Application<br/>[main.py]"]
  node_migration_routes["Migration Routes<br/>[migration.py]"]
  node_metadata_routes["Metadata Routes<br/>[metadata.py]"]
  node_dependency_routes["Dependency Routes<br/>[dependencies.py]"]
  node_impact_routes["Impact Routes<br/>[impact.py]"]
  node_risk_routes["Risk Routes<br/>[risk.py]"]
  node_source_routes["Source Routes<br/>[source.py]"]
end

subgraph group_analysis["Analysis Engine"]
  node_orchestrator["Analysis Orchestrator"]
  node_parser["Migration Parser"]
  node_extractor["AST Dependency Extractor<br/>[extractor.py]"]
  node_graph_builder["Dependency Graph Builder<br/>[graph_builder.py]"]
end

subgraph group_ingestion["Source and Metadata"]
  node_source_connector["Source Connector<br/>[connector.py]"]
  node_metadata_service["PostgreSQL Metadata<br/>[service.py]"]
end

subgraph group_findings["Impact and Risk"]
  node_impact_service["Impact Analysis<br/>[service.py]"]
  node_risk_service["Risk Assessment<br/>[service.py]"]
end

node_user(("Engineer"))
node_postgres[("PostgreSQL")]
node_github["GitHub Repository"]

node_user -->|"uses"| node_views
node_views -->|"includes"| node_change_view
node_views -->|"includes"| node_overview_view
node_views -->|"renders in"| node_dashboard_layout
node_change_view -->|"requests analysis"| node_migration_service
node_change_view -->|"uses config"| node_scanner_service
node_overview_view -->|"loads migration data"| node_migration_service
node_overview_view -->|"loads scan data"| node_scanner_service
node_overview_view -->|"loads risk data"| node_risk_service
node_migration_service -->|"sends requests"| node_http_client
node_scanner_service -->|"sends requests"| node_http_client
node_http_client -.->|"HTTP requests"| node_api_app
node_api_app -->|"mounts"| node_migration_routes
node_api_app -->|"mounts"| node_metadata_routes
node_api_app -->|"mounts"| node_dependency_routes
node_api_app -->|"mounts"| node_impact_routes
node_api_app -->|"mounts"| node_risk_routes
node_api_app -->|"mounts"| node_source_routes
node_migration_routes -->|"parses SQL"| node_parser
node_metadata_routes -->|"inspects schema"| node_metadata_service
node_dependency_routes -->|"runs unified analysis"| node_orchestrator
node_dependency_routes -->|"extracts dependencies"| node_extractor
node_dependency_routes -->|"parses migration"| node_parser
node_impact_routes -->|"assesses impact"| node_impact_service
node_risk_routes -->|"scores risk"| node_risk_service
node_source_routes -->|"ingests source"| node_source_connector
node_orchestrator -->|"parses migration"| node_parser
node_orchestrator -->|"verifies schema"| node_metadata_service
node_orchestrator -->|"extracts dependencies"| node_extractor
node_orchestrator -->|"builds graph"| node_graph_builder
node_orchestrator -->|"selects source"| node_source_connector
node_extractor -->|"delegates graphing"| node_graph_builder
node_impact_service -->|"uses dependencies"| node_extractor
node_impact_service -->|"uses migration data"| node_parser
node_impact_service -->|"uses metadata"| node_metadata_service
node_risk_service -->|"scores impact report"| node_impact_service
node_metadata_service -->|"reads catalogs"| node_postgres
node_source_connector -->|"fetches repository"| node_github

click node_views "https://github.com/ayushgadag/dbscope/tree/main/frontend/src/pages"
click node_change_view "https://github.com/ayushgadag/dbscope/blob/main/frontend/src/pages/AnalyzeChange.tsx"
click node_overview_view "https://github.com/ayushgadag/dbscope/blob/main/frontend/src/pages/Overview.tsx"
click node_dashboard_layout "https://github.com/ayushgadag/dbscope/blob/main/frontend/src/layouts/DashboardLayout.tsx"
click node_migration_service "https://github.com/ayushgadag/dbscope/blob/main/frontend/src/services/migrationService.ts"
click node_scanner_service "https://github.com/ayushgadag/dbscope/blob/main/frontend/src/services/scannerService.ts"
click node_http_client "https://github.com/ayushgadag/dbscope/blob/main/frontend/src/services/api.ts"
click node_api_app "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/main.py"
click node_migration_routes "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/migration.py"
click node_metadata_routes "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/metadata.py"
click node_dependency_routes "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/dependencies.py"
click node_impact_routes "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/impact.py"
click node_risk_routes "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/risk.py"
click node_source_routes "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/source.py"
click node_orchestrator "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/analysis_service.py"
click node_parser "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/migration_parser.py"
click node_extractor "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/dependencies/extractor.py"
click node_graph_builder "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/dependencies/graph_builder.py"
click node_source_connector "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/source/connector.py"
click node_metadata_service "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/metadata/service.py"
click node_impact_service "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/impact/service.py"
click node_risk_service "https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/risk/service.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_views,node_change_view,node_overview_view,node_dashboard_layout,node_migration_service,node_scanner_service,node_http_client toneBlue
class node_api_app,node_migration_routes,node_metadata_routes,node_dependency_routes,node_impact_routes,node_risk_routes,node_source_routes,node_postgres toneAmber
class node_orchestrator,node_parser,node_extractor,node_graph_builder toneMint
class node_source_connector,node_metadata_service toneRose
class node_impact_service,node_risk_service,node_user,node_github toneIndigo
```

## Components

### Dashboard

- [Analysis Views](https://github.com/ayushgadag/dbscope/tree/main/frontend/src/pages): `frontend/src/pages`
- [Analyze Change](https://github.com/ayushgadag/dbscope/blob/main/frontend/src/pages/AnalyzeChange.tsx): `frontend/src/pages/AnalyzeChange.tsx`
- [Overview](https://github.com/ayushgadag/dbscope/blob/main/frontend/src/pages/Overview.tsx): `frontend/src/pages/Overview.tsx`
- [Dashboard Layout](https://github.com/ayushgadag/dbscope/blob/main/frontend/src/layouts/DashboardLayout.tsx): `frontend/src/layouts/DashboardLayout.tsx`
- [Migration Service](https://github.com/ayushgadag/dbscope/blob/main/frontend/src/services/migrationService.ts): `frontend/src/services/migrationService.ts`
- [Scanner Service](https://github.com/ayushgadag/dbscope/blob/main/frontend/src/services/scannerService.ts): `frontend/src/services/scannerService.ts`
- [HTTP Client](https://github.com/ayushgadag/dbscope/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### REST API

- [FastAPI Application](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/main.py): `backend/dbscope/api/main.py`
- [Migration Routes](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/migration.py): `backend/dbscope/api/routes/migration.py`
- [Metadata Routes](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/metadata.py): `backend/dbscope/api/routes/metadata.py`
- [Dependency Routes](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/dependencies.py): `backend/dbscope/api/routes/dependencies.py`
- [Impact Routes](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/impact.py): `backend/dbscope/api/routes/impact.py`
- [Risk Routes](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/risk.py): `backend/dbscope/api/routes/risk.py`
- [Source Routes](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/api/routes/source.py): `backend/dbscope/api/routes/source.py`

### Analysis Engine

- [Analysis Orchestrator](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/analysis_service.py): `backend/dbscope/analysis_service.py`
- [Migration Parser](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/migration_parser.py): `backend/dbscope/migration_parser.py`
- [AST Dependency Extractor](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/dependencies/extractor.py): `backend/dbscope/dependencies/extractor.py`
- [Dependency Graph Builder](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/dependencies/graph_builder.py): `backend/dbscope/dependencies/graph_builder.py`

### Source and Metadata

- [Source Connector](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/source/connector.py): `backend/dbscope/source/connector.py`
- [PostgreSQL Metadata](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/metadata/service.py): `backend/dbscope/metadata/service.py`

### Impact and Risk

- [Impact Analysis](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/impact/service.py): `backend/dbscope/impact/service.py`
- [Risk Assessment](https://github.com/ayushgadag/dbscope/blob/main/backend/dbscope/risk/service.py): `backend/dbscope/risk/service.py`

### Other components

- **Engineer**
- **PostgreSQL**
- **GitHub Repository**

## Connections

- Engineer → Analysis Views: uses (evidence: `README.md`)
- Analysis Views → Analyze Change: includes (evidence: `frontend/src/router/index.tsx`)
- Analysis Views → Overview: includes (evidence: `frontend/src/router/index.tsx`)
- Analysis Views → Dashboard Layout: renders in (evidence: `frontend/src/router/index.tsx`)
- Analyze Change → Migration Service: requests analysis (evidence: `frontend/src/pages/AnalyzeChange.tsx`)
- Analyze Change → Scanner Service: uses config (evidence: `frontend/src/pages/AnalyzeChange.tsx`)
- Overview → Migration Service: loads migration data (evidence: `frontend/src/pages/Overview.tsx`)
- Overview → Scanner Service: loads scan data (evidence: `frontend/src/pages/Overview.tsx`)
- Overview → Risk Assessment: loads risk data (evidence: `frontend/src/pages/Overview.tsx`)
- Migration Service → HTTP Client: sends requests (evidence: `frontend/src/services/migrationService.ts`)
- Scanner Service → HTTP Client: sends requests (evidence: `frontend/src/services/scannerService.ts`)
- HTTP Client → FastAPI Application: HTTP requests (evidence: `frontend/src/services/api.ts`)
- FastAPI Application → Migration Routes: mounts (evidence: `backend/dbscope/api/main.py`)
- FastAPI Application → Metadata Routes: mounts (evidence: `backend/dbscope/api/main.py`)
- FastAPI Application → Dependency Routes: mounts (evidence: `backend/dbscope/api/main.py`)
- FastAPI Application → Impact Routes: mounts (evidence: `backend/dbscope/api/main.py`)
- FastAPI Application → Risk Routes: mounts (evidence: `backend/dbscope/api/main.py`)
- FastAPI Application → Source Routes: mounts (evidence: `backend/dbscope/api/main.py`)
- Migration Routes → Migration Parser: parses SQL (evidence: `backend/dbscope/api/routes/migration.py`)
- Metadata Routes → PostgreSQL Metadata: inspects schema (evidence: `backend/dbscope/api/routes/metadata.py`)
- Dependency Routes → Analysis Orchestrator: runs unified analysis (evidence: `backend/dbscope/api/routes/dependencies.py`)
- Dependency Routes → AST Dependency Extractor: extracts dependencies (evidence: `backend/dbscope/api/routes/dependencies.py`)
- Dependency Routes → Migration Parser: parses migration (evidence: `backend/dbscope/api/routes/dependencies.py`)
- Impact Routes → Impact Analysis: assesses impact (evidence: `backend/dbscope/api/routes/impact.py`)
- Risk Routes → Risk Assessment: scores risk (evidence: `backend/dbscope/api/routes/risk.py`)
- Source Routes → Source Connector: ingests source (evidence: `backend/dbscope/api/routes/source.py`)
- Analysis Orchestrator → Migration Parser: parses migration (evidence: `backend/dbscope/analysis_service.py`)
- Analysis Orchestrator → PostgreSQL Metadata: verifies schema (evidence: `backend/dbscope/analysis_service.py`)
- Analysis Orchestrator → AST Dependency Extractor: extracts dependencies (evidence: `backend/dbscope/analysis_service.py`)
- Analysis Orchestrator → Dependency Graph Builder: builds graph (evidence: `backend/dbscope/analysis_service.py`)
- Analysis Orchestrator → Source Connector: selects source (evidence: `backend/dbscope/analysis_service.py`)
- AST Dependency Extractor → Dependency Graph Builder: delegates graphing (evidence: `backend/dbscope/dependencies/extractor.py`)
- Impact Analysis → AST Dependency Extractor: uses dependencies (evidence: `backend/dbscope/impact/service.py`)
- Impact Analysis → Migration Parser: uses migration data (evidence: `backend/dbscope/impact/service.py`)
- Impact Analysis → PostgreSQL Metadata: uses metadata (evidence: `backend/dbscope/impact/service.py`)
- Risk Assessment → Impact Analysis: scores impact report (evidence: `backend/dbscope/risk/service.py`)
- PostgreSQL Metadata → PostgreSQL: reads catalogs (evidence: `backend/dbscope/metadata/service.py`)
- Source Connector → GitHub Repository: fetches repository (evidence: `backend/dbscope/source/connector.py`)
