# sunbos/sqlseed architecture

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

## Overview

sqlseed generates reproducible test rows for existing SQLite and PostgreSQL schemas, with Python, terminal, browser, and MCP entry points. The main path reads schema and reusable rules, infers or applies column generators, orders related tables, and previews or inserts rows. Optional AI suggests rules and analyzes or repairs configurations; it is not required for core generation. The README documents these capabilities, while sampled source confirms the CLI, MCP, query, validator, repair, and web navigation responsibilities; some unsampled subsystem links are therefore omitted.

Main entry points: [`src/sqlseed/core/orchestrator/__init__.py`](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/__init__.py) (Data orchestrator), [`plugins/sqlseed-ai/src/sqlseed_ai/auto_heal/orchestrator.py`](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/auto_heal/orchestrator.py) (Analyze and heal), [`src/sqlseed/core/orchestrator/_generation.py`](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/_generation.py) (Row generation), [`plugins/sqlseed-cli/src/sqlseed_cli/main.py`](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-cli/src/sqlseed_cli/main.py) (Terminal CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Generation core"]
  node_config["Rules and config<br/>[loader.py]"]
  node_orchestrator["Data orchestrator<br/>[__init__.py]"]
  node_schema["Schema mapping<br/>[_query.py]"]
  node_relationships["Dependency ordering<br/>[relation.py]"]
  node_generation["Row generation<br/>[_generation.py]"]
  node_preview["Sample preview<br/>[_generation.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_cli["Terminal CLI<br/>[main.py]"]
  node_web["Web workbench<br/>[app.py]"]
  node_web_ui["Browser UI<br/>[app.js]"]
  node_mcp["Core MCP tools<br/>[server.py]"]
end

subgraph group_ai["AI assistance"]
  node_ai_commands["AI commands<br/>[ai_commands.py]"]
  node_ai_mediator["AI rule suggestions<br/>[ai_mediator.py]"]
  node_auto_heal["Analyze and heal<br/>[orchestrator.py]"]
  node_validator["Constraint validator<br/>[main.py]"]
  node_repair["Rule repair<br/>[pipeline.py]"]
end

subgraph group_providers["Database and generators"]
  node_database[("Target database")]
  node_generators["Value providers<br/>[registry.py]"]
end

subgraph group_plugins["Extensions"]
  node_plugin_manager["Plugin manager<br/>[manager.py]"]
end

node_user(("User"))
node_llm(("Model service"))

node_user -->|"calls"| node_python_api
node_user -->|"runs"| node_cli
node_user -->|"uses"| node_web_ui
node_user -->|"invokes tools"| node_mcp
node_web_ui -->|"requests"| node_web
node_python_api -->|"starts generation"| node_orchestrator
node_cli -->|"loads rules"| node_config
node_cli -->|"fills or previews"| node_orchestrator
node_mcp -->|"fills table"| node_orchestrator
node_mcp -->|"reads mapping"| node_schema
node_config -->|"supplies rules"| node_orchestrator
node_orchestrator -->|"reads metadata"| node_schema
node_schema -->|"inspects schema"| node_database
node_orchestrator -->|"orders tables"| node_relationships
node_orchestrator -->|"coordinates rows"| node_generation
node_generation -->|"requests values"| node_generators
node_generation -->|"inserts rows"| node_database
node_preview -->|"samples rules"| node_generation
node_ai_commands -->|"suggests rules"| node_ai_mediator
node_ai_commands -->|"analyzes or heals"| node_auto_heal
node_auto_heal -->|"validates config"| node_validator
node_auto_heal -->|"repairs violations"| node_repair
node_repair -->|"revalidates partial fixes"| node_validator
node_ai_mediator -->|"requests suggestions"| node_llm
node_auto_heal -.->|"requests rule help"| node_llm
node_orchestrator -.->|"loads extensions"| node_plugin_manager

click node_python_api "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/__init__.py"
click node_cli "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-cli/src/sqlseed_cli/main.py"
click node_web "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-web/src/sqlseed_web/app.py"
click node_web_ui "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-web/src/sqlseed_web/static/js/app.js"
click node_mcp "https://github.com/sunbos/sqlseed/blob/main/plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/server.py"
click node_config "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/config/loader.py"
click node_orchestrator "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/__init__.py"
click node_schema "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/_query.py"
click node_relationships "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/relation.py"
click node_generation "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/_generation.py"
click node_preview "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/_generation.py"
click node_database "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/database/sqlalchemy_adapter.py"
click node_generators "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/generators/registry.py"
click node_ai_commands "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/cli/ai_commands.py"
click node_ai_mediator "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/ai_mediator.py"
click node_auto_heal "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/auto_heal/orchestrator.py"
click node_validator "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/validator/main.py"
click node_repair "https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/repair/pipeline.py"
click node_plugin_manager "https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/plugins/manager.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_config,node_orchestrator,node_schema,node_relationships,node_generation,node_preview,node_user toneBlue
class node_python_api,node_cli,node_web,node_web_ui,node_mcp toneAmber
class node_ai_commands,node_ai_mediator,node_auto_heal,node_validator,node_repair toneMint
class node_database,node_generators toneRose
class node_plugin_manager,node_llm toneIndigo
```

## Components

### Generation core

- [Rules and config](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/config/loader.py): `src/sqlseed/config/loader.py`
- [Data orchestrator](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/__init__.py): `src/sqlseed/core/orchestrator/__init__.py`
- [Schema mapping](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/_query.py): `src/sqlseed/core/orchestrator/_query.py`
- [Dependency ordering](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/relation.py): `src/sqlseed/core/relation.py`
- [Row generation](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/_generation.py): `src/sqlseed/core/orchestrator/_generation.py`
- [Sample preview](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/core/orchestrator/_generation.py): `src/sqlseed/core/orchestrator/_generation.py`

### User interfaces

- [Python API](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/__init__.py): `src/sqlseed/__init__.py`
- [Terminal CLI](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-cli/src/sqlseed_cli/main.py): `plugins/sqlseed-cli/src/sqlseed_cli/main.py`
- [Web workbench](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-web/src/sqlseed_web/app.py): `plugins/sqlseed-web/src/sqlseed_web/app.py`
- [Browser UI](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-web/src/sqlseed_web/static/js/app.js): `plugins/sqlseed-web/src/sqlseed_web/static/js/app.js`
- [Core MCP tools](https://github.com/sunbos/sqlseed/blob/main/plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/server.py): `plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/server.py`

### AI assistance

- [AI commands](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/cli/ai_commands.py): `plugins/sqlseed-ai/src/sqlseed_ai/cli/ai_commands.py`
- [AI rule suggestions](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/ai_mediator.py): `plugins/sqlseed-ai/src/sqlseed_ai/ai_mediator.py`
- [Analyze and heal](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/auto_heal/orchestrator.py): `plugins/sqlseed-ai/src/sqlseed_ai/auto_heal/orchestrator.py`
- [Constraint validator](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/validator/main.py): `plugins/sqlseed-ai/src/sqlseed_ai/validator/main.py`
- [Rule repair](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/repair/pipeline.py): `plugins/sqlseed-ai/src/sqlseed_ai/repair/pipeline.py`

### Database and generators

- [Target database](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/database/sqlalchemy_adapter.py): `src/sqlseed/database/sqlalchemy_adapter.py`
- [Value providers](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/generators/registry.py): `src/sqlseed/generators/registry.py`

### Extensions

- [Plugin manager](https://github.com/sunbos/sqlseed/blob/main/src/sqlseed/plugins/manager.py): `src/sqlseed/plugins/manager.py`

### Other components

- **User**
- **Model service**

## Connections

- User → Python API: calls
- User → Terminal CLI: runs
- User → Browser UI: uses
- User → Core MCP tools: invokes tools
- Browser UI → Web workbench: requests
- Python API → Data orchestrator: starts generation
- Terminal CLI → Rules and config: loads rules
- Terminal CLI → Data orchestrator: fills or previews
- Core MCP tools → Data orchestrator: fills table
- Core MCP tools → Schema mapping: reads mapping
- Rules and config → Data orchestrator: supplies rules
- Data orchestrator → Schema mapping: reads metadata
- Schema mapping → Target database: inspects schema
- Data orchestrator → Dependency ordering: orders tables
- Data orchestrator → Row generation: coordinates rows
- Row generation → Value providers: requests values
- Row generation → Target database: inserts rows
- Sample preview → Row generation: samples rules
- AI commands → AI rule suggestions: suggests rules
- AI commands → Analyze and heal: analyzes or heals
- Analyze and heal → Constraint validator: validates config
- Analyze and heal → Rule repair: repairs violations
- Rule repair → Constraint validator: revalidates partial fixes
- AI rule suggestions → Model service: requests suggestions
- Analyze and heal → Model service: requests rule help
- Data orchestrator → Plugin manager: loads extensions