# midedickson/chatabase architecture

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

- Interactive diagram: https://gitdiagram.com/midedickson/chatabase
- Repository: https://github.com/midedickson/chatabase

## Overview

##### Project type and purpose
- Chatabase is an open-source Go library (package) whose sole purpose is to take a declarative chart configuration and produce a parameterized SQL query. It is not a full-stack application, but rather a self-contained utility that integrates into larger applications (e.g., BI dashboards, analytics platforms).

##### File structure
- Top level:
- chartconfig.go – defines ChartConfig, TableConfig, JoinConfig, AxisConfig, FilterConfig, OrderConfig, ChartOptions
- query.go – public BuildChartQuery entry point
- querybuilder.go – core engine that composes SQL fragments
- dbanalyzer.go – inspects table metadata or handles DB-specific quirks
- queryrow.go – mapping results to rows (optional)
- example/main.go – sample consumer application showing usage
- go.mod / go.sum, LICENSE, README.md
- No “frontend” or “backend” directories; it’s a single-module library. The example directory shows an integration point.

##### Extract insights from the README
- Core components: configuration loading (JSON or struct), validation & normalization, SQL generation with safe parameterization, JSON file I/O, multiple chart types, filtering, aggregation, joins.

a. Main components
1. Consumer Application (e.g., BI Dashboard, CLI example)
2. Configuration Loader & Parser
3. Validator & Normalizer
4. Query Builder
5. DB Analyzer / Dialect Handler
6. JSON File I/O module
7. External Systems:
– Relational Database (Postgres, MySQL, etc.)
– File System (for JSON config)
b. Relationships & data flow
1. Consumer Application initializes ChartConfig (struct or JSON file).
→ [Config Loader] reads JSON or takes in-memory struct.
2. Loader passes config to [Validator].
→ Validator checks required fields, types, default values.
3. Validated config is fed into [Query Builder].
→ Query Builder invokes [DB Analyzer] to adapt SQL to target dialect or introspect schema.
→ Query Builder creates SQL template + args.
4. Query + args are returned to Consumer.
→ Consumer executes the query on the Relational Database.
5. Optionally, Consumer can call [JSON File I/O] to save chart configuration or load another.
c. Architectural patterns & design principles
- Builder pattern: QueryBuilder composes SQL fragments step by step.
- Separation of concerns: config parsing/validation, SQL generation, DB adaptation, JSON I/O are distinct modules.
- Strong typing (Go structs) ensures compile-time safety.
- Parameterized queries prevent SQL injection.
d. Key technologies & libraries
- Go language (go.mod)
- Standard library JSON (`encoding/json`)
- SQL driver interfaces (database/sql)
- No external dependencies beyond core language and SQL drivers.

##### Detail
- Support for multiple chart types as a branching decision within QueryBuilder.
- How FilterConfig maps to WHERE clauses, AxisConfig to SELECT/GROUP BY clauses, JoinConfig to JOIN clauses.

Final advice:
- Sketch the high-level modules first, then drill into QueryBuilder’s internal pipeline:
parse ChartConfig → build SELECT clauses → build JOINs → build WHERE filters → build GROUP BY/HAVING → build ORDER BY/LIMIT → output parameterized SQL.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Consumer Application"]:::external
    subgraph "Library Modules"
        Loader["Config Loader & Parser"]:::library
        Validator["Validator & Normalizer"]:::library
        QE["Query Builder (Entry)"]:::library
        Engine["Core Query Builder Engine"]:::library
        Analyzer["DB Analyzer / Dialect Handler"]:::library
        QRow["Query Row Mapper"]:::library
        JSONIO["JSON I/O Module"]:::library
    end
    subgraph "External Systems"
        DB[(Relational Database)]:::external
        FS[(File System / JSON files)]:::external
    end

    A -->|"ChartConfig struct/JSON"| Loader
    Loader -->|"Loaded Config"| Validator
    Validator -->|"ValidatedConfig"| QE
    QE -->|"Build Steps"| Engine
    Engine -->|"Dialect Info"| Analyzer
    Analyzer -->|"Schema/Adapted Info"| Engine
    Engine -->|"SQL + []args"| QE
    QE -->|"SQL + args"| A
    A -->|"Exec SQL"| DB

    A <-->|"Save/Load Config"| JSONIO
    JSONIO -->|"Read/Write JSON"| FS
    FS -->|"JSON file"| JSONIO

    click A "https://github.com/midedickson/chatabase/blob/main/example/main.go"
    click Loader "https://github.com/midedickson/chatabase/blob/main/chartconfig.go"
    click Validator "https://github.com/midedickson/chatabase/blob/main/chartconfig.go"
    click QE "https://github.com/midedickson/chatabase/blob/main/query.go"
    click Engine "https://github.com/midedickson/chatabase/blob/main/querybuilder.go"
    click Analyzer "https://github.com/midedickson/chatabase/blob/main/dbanalyzer.go"
    click QRow "https://github.com/midedickson/chatabase/blob/main/queryrow.go"

    classDef library fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFD580,stroke:#333,stroke-width:1px
```
