# skanga/dbchat architecture

> Architecture diagram of the GitHub repository skanga/dbchat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skanga/dbchat
- Repository: https://github.com/skanga/dbchat

## Overview

##### Project type and purpose
- DBChat is a standalone Java-based MCP (Model Context Protocol) server that exposes a natural-language interface to arbitrary JDBC databases.
- It is not a typical multi-tier full-stack app; rather, it’s a backend service (“MCP server”) that you run as a JAR, which your MCP-aware client (e.g., Claude Desktop) connects to over STDIN/STDOUT or HTTP.

##### File structure
- Top-level: pom.xml (Maven), build & release scripts, documentation (INSTALL.md, VISUALIZATION.md, MCP-SETUP.md).
- src/main/java/com/skanga/init – configuration and CLI parsing.
- src/main/java/com/skanga/mcp – core server bootstrap (McpServer), protocol handlers (HealthCheckHandler), HTTP adapter (McpHttpHandler), security utilities.
- src/main/java/com/skanga/mcp/config – parameter definitions (ConfigParams), CLI utilities, ResourceManager (registers MCP resources).
- src/main/java/com/skanga/mcp/db – data-access layer: DatabaseService (JDBC pooling), DatabaseResource (exposes SQL endpoints), QueryResult.
- Modules under mcp/demo, mcp/insights, mcp/prompts, mcp/workflow – each providing a specialized service and registering MCP handlers.
- src/main/resources – application.properties and per-DB YAML configs.

##### README
- Confirms architecture: a single JAR that implements MCP protocol handlers for prompts, workflows, insights, demo data, and SQL operations.
- Supports both STDIN/STDOUT MCP clients and an optional HTTP listener.
- Emphasizes modular “prompt” and “workflow” subsystems, dynamic discovery of resources via MCP protocol.

##### Main components
a. Entry points:
- MCP Client (e.g., Claude Desktop) – STDIN/STDOUT or HTTP
- CLI args / Environment variables – initial configuration
b. Core server:
- ClientConfig & CliUtils – parse args, load config file, env vars
- McpServer – main loop, routes incoming MCP requests to handlers
- McpHttpHandler – optional HTTP adapter forwarding HTTP calls into MCP pipeline
- ResourceManager – registry of available MCP resource endpoints
c. Protocol handlers (registered in ResourceManager):
- HealthCheckHandler
- McpHttpHandler (if HTTP_MODE=true)
- Prompts module – PromptService, PromptTemplate
- Workflow module – WorkflowManager, WorkflowService
- Demo module – DemoDataGenerator, DemoDataService, BusinessScenario
- Insights module – InsightsService, InsightsMemo, BusinessInsight
- Database module – DatabaseResource, DatabaseService, QueryResult
d. External dependencies:
- JDBC driver (MySQL, PostgreSQL, SQLite, etc)
- Underlying database(s)
- File system – YAML configs, JSON persistence for insights/demo state

##### Relationships & interactions
1. MCP Client → (STDIN/STDOUT or HTTP) → McpServer / McpHttpHandler
2. McpServer looks up resource in ResourceManager → invokes appropriate Handler
3. Handler uses one or more Services:
- DatabaseResource calls DatabaseService → JDBC → Database
- PromptService loads PromptTemplate → returns prompt metadata or content
- WorkflowService / WorkflowManager manage state machine for interactive workflows
- DemoDataService / DemoDataGenerator populate database with scenario data
- InsightsService / InsightsMemo accumulate and persist business insights
4. Service returns domain object (QueryResult, BusinessInsight, PromptTemplate, WorkflowState) → Handler serializes to JSON/MCP protocol → McpServer → MCP Client

##### Architectural patterns & design principles
- Layered/hexagonal architecture: separation of transport (MCP/HTTP), handler layer, service/domain layer, and infrastructure (DB, file system).
- Plugin-style modules: each feature (prompts, workflow, insights, demo) registers itself via ResourceManager.
- Configuration priority: CLI args → config file → environment vars → system properties → defaults.
- Stateless request handling in services except the workflow state manager, which persists JSON state.
- Clean separation of concerns: protocol parsing vs. business logic vs. persistence.

##### Essential architectural elements to capture
- Dual transport: STDIN/STDOUT MCP protocol and optional HTTP
- ResourceManager as the registry
- Modular handlers for prompts, workflows, insights, demos, SQL
- DatabaseService as the unified data-access component
- Configuration hierarchy
- External dependencies (JDBC drivers, target databases)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry & Configuration
    subgraph "Entry & Configuration"
        direction TB
        ClientConfig["ClientConfig"]:::config
        CliUtils["CliUtils"]:::config
        ConfigParams["ConfigParams"]:::config
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        MCPClient["MCP Client\n(STDIN/STDOUT)"]:::transport
        HTTPClient["MCP Client\n(HTTP)"]:::transport
    end

    %% Handler Layer
    subgraph "Handler Layer"
        direction TB
        McpServer["McpServer"]:::handler
        McpHttpHandler["McpHttpHandler"]:::handler
        ResourceManager["ResourceManager"]:::handler
        HealthCheckHandler["HealthCheckHandler"]:::handler
    end

    %% Service/Domain Layer
    subgraph "Service & Domain Layer"
        direction TB
        DatabaseService["DatabaseService"]:::service
        DatabaseResource["DatabaseResource"]:::service
        QueryResult["QueryResult"]:::domain
        PromptService["PromptService"]:::service
        PromptTemplate["PromptTemplate"]:::domain
        WorkflowService["WorkflowService"]:::service
        WorkflowManager["WorkflowManager"]:::service
        DemoDataService["DemoDataService"]:::service
        DemoDataGenerator["DemoDataGenerator"]:::service
        BusinessScenario["BusinessScenario"]:::domain
        InsightsService["InsightsService"]:::service
        InsightsMemo["InsightsMemo"]:::domain
        BusinessInsight["BusinessInsight"]:::domain
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        JDBCDriver["JDBC Driver"]:::infra
        Database["Database"]:::infra
        FileSystem["File System\n(YAML/Properties)"]:::infra
    end

    %% Configuration Flow
    ClientConfig -->|loads| ResourceManager
    CliUtils -->|parses args| ResourceManager
    ConfigParams -->|defines params| ResourceManager

    %% Transport to Handler
    MCPClient -->|STDIN/STDOUT| McpServer
    HTTPClient -->|HTTP Requests| McpHttpHandler
    McpHttpHandler -->|invokeHandler| McpServer

    %% Handler Registry
    McpServer -->|registerHandlers| ResourceManager
    ResourceManager -->|holds| HealthCheckHandler
    ResourceManager -->|holds| McpHttpHandler
    ResourceManager -->|holds| PromptService
    ResourceManager -->|holds| WorkflowService
    ResourceManager -->|holds| DemoDataService
    ResourceManager -->|holds| InsightsService
    ResourceManager -->|holds| DatabaseResource

    %% Request Flow
    McpServer -->|invokeHandler| HealthCheckHandler
    McpServer -->|invokeHandler| PromptService
    McpServer -->|invokeHandler| WorkflowService
    McpServer -->|invokeHandler| DemoDataService
    McpServer -->|invokeHandler| InsightsService
    McpServer -->|invokeHandler| DatabaseResource

    %% Handler to Service
    DatabaseResource -->|executeQuery| DatabaseService
    PromptService -->|loadTemplate| PromptTemplate
    WorkflowService -->|orchestrate| WorkflowManager
    DemoDataService -->|generateData| DemoDataGenerator
    InsightsService -->|persistInsight| InsightsMemo

    %% Service to Infrastructure
    DatabaseService -->|JDBC Calls| JDBCDriver
    JDBCDriver -->|connects to| Database
    ResourceManager -->|reads| FileSystem
    PromptTemplate -->|reads| FileSystem
    BusinessScenario -->|defined in| FileSystem
    InsightsMemo -->|persisted in| FileSystem

    %% Return Flow
    DatabaseService -->|returns| QueryResult
    InsightsService -->|returns| BusinessInsight

    %% Click Events
    click ClientConfig "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/init/ClientConfig.java"
    click CliUtils "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/config/CliUtils.java"
    click ConfigParams "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/config/ConfigParams.java"
    click McpServer "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/McpServer.java"
    click McpHttpHandler "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/McpHttpHandler.java"
    click HealthCheckHandler "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/HealthCheckHandler.java"
    click ResourceManager "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/config/ResourceManager.java"
    click DatabaseService "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/db/DatabaseService.java"
    click DatabaseResource "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/db/DatabaseResource.java"
    click QueryResult "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/db/QueryResult.java"
    click PromptService "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/prompts/PromptService.java"
    click PromptTemplate "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/prompts/PromptTemplate.java"
    click WorkflowManager "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/workflow/WorkflowManager.java"
    click WorkflowService "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/workflow/WorkflowService.java"
    click DemoDataGenerator "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/demo/DemoDataGenerator.java"
    click DemoDataService "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/demo/DemoDataService.java"
    click BusinessScenario "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/demo/BusinessScenario.java"
    click InsightsService "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/insights/InsightsService.java"
    click InsightsMemo "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/insights/InsightsMemo.java"
    click BusinessInsight "https://github.com/skanga/dbchat/blob/main/src/main/java/com/skanga/mcp/insights/BusinessInsight.java"

    %% Styles
    classDef transport fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef handler fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef service fill:#fff2b2,stroke:#333,stroke-width:1px
    classDef domain fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef config fill:#ffe6e6,stroke:#333,stroke-width:1px
```
