# raghuraj09/schemamorph-ai architecture

> Architecture diagram of the GitHub repository raghuraj09/schemamorph-ai, 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/raghuraj09/schemamorph-ai
- Repository: https://github.com/raghuraj09/schemamorph-ai

## Overview

SchemaMorph AI turns uploaded PostgreSQL schemas and workload queries into proposed microservice boundaries, validation findings, per-service DDL, and reports. Its principal workflow is upload → parse → build and partition a weighted dependency graph → add AI narration → validate → generate outputs → inspect them in the dashboard. Authentication and project history support that workflow. The README documents the analysis stages and major UI capabilities; some backend orchestration and frontend page wiring were not sampled, so those links rely on README statements rather than inspected call sites.

Main entry points: [`backend/app/api/v1/analysis.py`](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/analysis.py) (Analysis endpoint), [`frontend/src/pages/Dashboard.jsx`](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/pages/Dashboard.jsx) (Analysis dashboard), [`backend/app/api/v1/router.py`](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/router.py) (Versioned API routes), [`frontend/src/api/client.js`](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/api/client.js) (HTTP API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_app["Web app routing<br/>[App.jsx]"]
  node_upload["Schema upload<br/>[Upload.jsx]"]
  node_dashboard["Analysis dashboard<br/>[Dashboard.jsx]"]
  node_history["Project history<br/>[History.jsx]"]
  node_visualization["Graph visualization<br/>[GraphView.jsx]"]
  node_servicepanel["Service details<br/>[ServicePanel.jsx]"]
  node_querydiff["Query findings<br/>[QueryDiff.jsx]"]
  node_client["HTTP API client<br/>[client.js]"]
  node_authstate["Authentication state<br/>[authStore.js]"]
end

subgraph group_api["API and persistence"]
  node_api["Versioned API routes<br/>[router.py]"]
  node_schemaapi["Schema endpoints<br/>[schema.py]"]
  node_queryapi["Query endpoints<br/>[queries.py]"]
  node_analysisapi["Analysis endpoint<br/>[analysis.py]"]
  node_database[("Project and run store<br/>[database.py]")]
end

subgraph group_analysis["Decomposition engine"]
  node_schemaparser["DDL parser<br/>[schema_parser.py]"]
  node_queryparser["Workload parser<br/>[query_parser.py]"]
  node_builder["Dependency graph<br/>[builder.py]"]
  node_clusterer["Community detection<br/>[clusterer.py]"]
  node_ai["AI narration<br/>[engine.py]"]
  node_prompts["Analysis prompts<br/>[prompts.py]"]
  node_validator["Integrity validation<br/>[validator.py]"]
  node_reports["DDL and reports<br/>[generator.py]"]
end

subgraph group_security["Identity"]
  node_authapi["Authentication endpoints<br/>[auth.py]"]
  node_security["JWT and passwords<br/>[security.py]"]
end

node_user(("Engineer"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_upload
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_history
node_upload -->|"uploads inputs"| node_client
node_dashboard -->|"requests analysis"| node_client
node_dashboard -->|"shows graph"| node_visualization
node_dashboard -->|"shows services"| node_servicepanel
node_dashboard -->|"shows query findings"| node_querydiff
node_history -->|"loads projects"| node_client
node_client -->|"reads token"| node_authstate
node_client -->|"calls endpoints"| node_api
node_api -->|"registers routes"| node_schemaapi
node_api -->|"registers routes"| node_queryapi
node_api -->|"registers routes"| node_analysisapi
node_schemaapi -->|"parses DDL"| node_schemaparser
node_queryapi -->|"parses queries"| node_queryparser
node_analysisapi -->|"builds graph"| node_builder
node_analysisapi -->|"partitions graph"| node_clusterer
node_analysisapi -->|"requests narration"| node_ai
node_ai -->|"formats prompts"| node_prompts
node_analysisapi -->|"validates partitions"| node_validator
node_analysisapi -->|"generates outputs"| node_reports
node_analysisapi -.->|"persists runs"| node_database
node_authapi -->|"reads and writes users"| node_database
node_authapi -->|"hashes and signs"| node_security
node_api -->|"registers routes"| node_authapi

click node_app "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/App.jsx"
click node_upload "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/pages/Upload.jsx"
click node_dashboard "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/pages/Dashboard.jsx"
click node_history "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/pages/History.jsx"
click node_visualization "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/components/GraphView.jsx"
click node_servicepanel "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/components/ServicePanel.jsx"
click node_querydiff "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/components/QueryDiff.jsx"
click node_client "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/api/client.js"
click node_authstate "https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/store/authStore.js"
click node_api "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/router.py"
click node_schemaapi "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/schema.py"
click node_queryapi "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/queries.py"
click node_analysisapi "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/analysis.py"
click node_database "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/models/database.py"
click node_schemaparser "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/parsers/schema_parser.py"
click node_queryparser "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/parsers/query_parser.py"
click node_builder "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/graph/builder.py"
click node_clusterer "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/graph/clusterer.py"
click node_ai "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/ai/engine.py"
click node_prompts "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/ai/prompts.py"
click node_validator "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/validation/validator.py"
click node_reports "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/reports/generator.py"
click node_authapi "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/auth.py"
click node_security "https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/core/security.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_upload,node_dashboard,node_history,node_visualization,node_servicepanel,node_querydiff,node_client,node_authstate toneBlue
class node_api,node_schemaapi,node_queryapi,node_analysisapi,node_database toneAmber
class node_schemaparser,node_queryparser,node_builder,node_clusterer,node_ai,node_prompts,node_validator,node_reports toneMint
class node_authapi,node_security toneRose
class node_user toneIndigo
```

## Components

### Web experience

- [Web app routing](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Schema upload](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/pages/Upload.jsx): `frontend/src/pages/Upload.jsx`
- [Analysis dashboard](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Project history](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/pages/History.jsx): `frontend/src/pages/History.jsx`
- [Graph visualization](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/components/GraphView.jsx): `frontend/src/components/GraphView.jsx`
- [Service details](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/components/ServicePanel.jsx): `frontend/src/components/ServicePanel.jsx`
- [Query findings](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/components/QueryDiff.jsx): `frontend/src/components/QueryDiff.jsx`
- [HTTP API client](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Authentication state](https://github.com/raghuraj09/schemamorph-ai/blob/main/frontend/src/store/authStore.js): `frontend/src/store/authStore.js`

### API and persistence

- [Versioned API routes](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Schema endpoints](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/schema.py): `backend/app/api/v1/schema.py`
- [Query endpoints](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/queries.py): `backend/app/api/v1/queries.py`
- [Analysis endpoint](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/analysis.py): `backend/app/api/v1/analysis.py`
- [Project and run store](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/models/database.py): `backend/app/models/database.py`

### Decomposition engine

- [DDL parser](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/parsers/schema_parser.py): `backend/app/parsers/schema_parser.py`
- [Workload parser](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/parsers/query_parser.py): `backend/app/parsers/query_parser.py`
- [Dependency graph](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/graph/builder.py): `backend/app/graph/builder.py`
- [Community detection](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/graph/clusterer.py): `backend/app/graph/clusterer.py`
- [AI narration](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/ai/engine.py): `backend/app/ai/engine.py`
- [Analysis prompts](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/ai/prompts.py): `backend/app/ai/prompts.py`
- [Integrity validation](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/validation/validator.py): `backend/app/validation/validator.py`
- [DDL and reports](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/reports/generator.py): `backend/app/reports/generator.py`

### Identity

- [Authentication endpoints](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [JWT and passwords](https://github.com/raghuraj09/schemamorph-ai/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Other components

- **Engineer**

## Connections

- Engineer → Web app routing: uses (evidence: `README.md`)
- Web app routing → Schema upload: routes to (evidence: `frontend/src/App.jsx`)
- Web app routing → Analysis dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Web app routing → Project history: routes to (evidence: `frontend/src/App.jsx`)
- Schema upload → HTTP API client: uploads inputs (evidence: `README.md`)
- Analysis dashboard → HTTP API client: requests analysis (evidence: `README.md`)
- Analysis dashboard → Graph visualization: shows graph (evidence: `README.md`)
- Analysis dashboard → Service details: shows services (evidence: `README.md`)
- Analysis dashboard → Query findings: shows query findings (evidence: `README.md`)
- Project history → HTTP API client: loads projects (evidence: `README.md`)
- HTTP API client → Authentication state: reads token (evidence: `frontend/src/api/client.js`)
- HTTP API client → Versioned API routes: calls endpoints (evidence: `README.md`)
- Versioned API routes → Schema endpoints: registers routes (evidence: `backend/app/api/v1/router.py`)
- Versioned API routes → Query endpoints: registers routes (evidence: `backend/app/api/v1/router.py`)
- Versioned API routes → Analysis endpoint: registers routes (evidence: `backend/app/api/v1/router.py`)
- Schema endpoints → DDL parser: parses DDL (evidence: `README.md`)
- Query endpoints → Workload parser: parses queries (evidence: `README.md`)
- Analysis endpoint → Dependency graph: builds graph (evidence: `README.md`)
- Analysis endpoint → Community detection: partitions graph (evidence: `README.md`)
- Analysis endpoint → AI narration: requests narration (evidence: `README.md`)
- AI narration → Analysis prompts: formats prompts (evidence: `backend/app/ai/engine.py`)
- Analysis endpoint → Integrity validation: validates partitions (evidence: `README.md`)
- Analysis endpoint → DDL and reports: generates outputs (evidence: `README.md`)
- Analysis endpoint → Project and run store: persists runs
- Authentication endpoints → Project and run store: reads and writes users (evidence: `backend/app/api/v1/auth.py`)
- Authentication endpoints → JWT and passwords: hashes and signs (evidence: `backend/app/api/v1/auth.py`)
- Versioned API routes → Authentication endpoints: registers routes (evidence: `backend/app/api/v1/router.py`)
