# stephenafamo/bob architecture

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

- Interactive diagram: https://gitdiagram.com/stephenafamo/bob
- Repository: https://github.com/stephenafamo/bob

## Overview

##### Project Type & Purpose
- Bob is a Go “SQL Access Toolkit”: a library plus a set of CLI code‐generation tools and documentation.
- It exposes a fluent query‐builder + executor at runtime, and separate code generators (bobgen‑mysql, bobgen‑psql, bobgen‑sqlite, etc.) that read your DB schema and emit strongly typed Go models, factories, and queries.

##### High‐Level Components
A. CLI/Codegen Tools (build-time)
- Entry points: generate.go, build.go, binder.go, hooks.go
- Sub‐binaries: gen/bobgen‑mysql, bobgen‑psql, bobgen‑sqlite, bobgen‑sql
- Codegen engine: gen/ (drivers, templates, plugin.go)
B. Core Library (runtime)
- clause/ & expr/: SQL query builder modules (SELECT, JOIN, WHERE, etc.)
- exec.go: SQL executor wrapping database/sql
- query.go, orm/: higher‐level ORM query abstractions
- types/: custom DB types (JSON, PG enums, arrays, etc.)
C. Dialects
- dialect/mysql, dialect/psql, dialect/sqlite
- Each implements SQL variations and hints for that engine.
D. Consumer Application
- Your application imports “github.com/stephenafamo/bob” + generated code.
- At runtime it builds queries via clause+expr, executes them via exec, maps rows into generated structs.
E. Database(s)
F. Documentation Website
- website/: A Docusaurus‐powered site hosting user docs and examples.

##### Relationships & Data Flows
- Build‐time: CLI tools → connect to Database (database/sql + driver) → introspect schema → pass schema into gen/ drivers & templates → emit Go source files on disk.
- Run‐time: Application → imports Core Library + generated code → builds SQL via clause/expr → hands SQL to exec.go + dialect → database/sql driver → Database → returns rows → mapped back into Go structs.
- Documentation: independent site, static build of markdown content.

##### Architectural Patterns & Principles
- Builder pattern for SQL clause/expr modules.
- Plugin/driver pattern in gen/ for supporting multiple dialect codegens.
- Strict separation of build‐time (code gen) vs run‐time (query build + execution).
- Modular monorepo: clear separation of core, dialects, gen, website, tests.

##### Essential Elements
- Distinguish build‑time vs run‑time with a visual divider or background shading.
- Don’t omit the plugin/driver layer in gen/, and the dialect abstractions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-Time Code Generation Phase
    subgraph "Build-Time Code Generation" 
        direction TB
        CLIEntry["CLI Entry Points"]:::cli
        subgraph "Entry Point Files"
            direction TB
            GenGo["generate.go"]:::cli
            BuildGo["build.go"]:::cli
            BinderGo["binder.go"]:::cli
            HooksGo["hooks.go"]:::cli
        end
        subgraph "Codegen Sub-Binaries"
            direction TB
            GenMySQL["bobgen-mysql"]:::cli
            GenPSQL["bobgen-psql"]:::cli
            GenSQLite["bobgen-sqlite"]:::cli
            GenSQL["bobgen-sql"]:::cli
        end
        subgraph "Codegen Engine (gen/)" 
            direction TB
            GenCore["gen.go & plugin.go"]:::cli
            GenConfig["config.go & output.go"]:::cli
            Drivers["drivers/"]:::cli
            Importers["importers/"]:::cli
            Templates["templates/ & helpers"]:::cli
        end
        CLIEntry -->|triggers| GenMySQL
        CLIEntry -->|triggers| GenPSQL
        CLIEntry -->|triggers| GenSQLite
        CLIEntry -->|triggers| GenSQL
        GenMySQL -->|introspect schema| DB[(Databases)]:::db
        GenPSQL -->|introspect schema| DB
        GenSQLite -->|introspect schema| DB
        GenSQL -->|introspect schema| DB
        DB -->|schema data| GenCore
        GenCore -->|use drivers & templates| Drivers
        Drivers -->|use templates| Templates
        Importers --> Templates
        Templates -->|emit Go code| GeneratedCode["Generated Code"]:::generated
    end

    %% Runtime Query Execution Phase
    subgraph "Runtime Query Flow"
        direction TB
        App["Consumer Application"]:::app
        GeneratedCode -->|import| App
        subgraph "Core Library" 
            direction TB
            Clause["clause/ & expr/"]:::core
            Exec["exec.go"]:::core
            ORM["orm/ & query.go"]:::core
            Types["types/"]:::core
        end
        App -->|build query| Clause
        Clause -->|SQL| Exec
        Exec -->|apply dialect| Dialects
        subgraph "Dialects"
            direction TB
            MySQLDialect["dialect/mysql"]:::dialect
            PSQLDialect["dialect/psql"]:::dialect
            SQLiteDialect["dialect/sqlite"]:::dialect
        end
        Dialects -->|execute SQL| DB
        DB -->|rows| Exec
        Exec -->|map rows| App
    end

    %% Documentation Website
    Website["Documentation Website"]:::web
    Website -->|serves docs| Users["Users"]:::external

    %% Click Events
    click GenGo "https://github.com/stephenafamo/bob/blob/main/./generate.go"
    click BuildGo "https://github.com/stephenafamo/bob/blob/main/./build.go"
    click BinderGo "https://github.com/stephenafamo/bob/blob/main/./binder.go"
    click HooksGo "https://github.com/stephenafamo/bob/blob/main/./hooks.go"
    click GenMySQL "https://github.com/stephenafamo/bob/blob/main/./gen/bobgen-mysql/main.go"
    click GenPSQL "https://github.com/stephenafamo/bob/blob/main/./gen/bobgen-psql/main.go"
    click GenSQL "https://github.com/stephenafamo/bob/blob/main/./gen/bobgen-sql/main.go"
    click GenSQLite "https://github.com/stephenafamo/bob/blob/main/./gen/bobgen-sqlite/main.go"
    click GenCore "https://github.com/stephenafamo/bob/blob/main/./gen/gen.go"
    click Drivers "https://github.com/stephenafamo/bob/tree/main/./gen/drivers/"
    click Importers "https://github.com/stephenafamo/bob/tree/main/./gen/importers/"
    click Templates "https://github.com/stephenafamo/bob/tree/main/./gen/templates/"
    click Clause "https://github.com/stephenafamo/bob/tree/main/./clause/"
    click Exec "https://github.com/stephenafamo/bob/blob/main/./exec.go"
    click ORM "https://github.com/stephenafamo/bob/tree/main/./orm/"
    click Types "https://github.com/stephenafamo/bob/tree/main/./types/"
    click MySQLDialect "https://github.com/stephenafamo/bob/tree/main/./dialect/mysql/"
    click PSQLDialect "https://github.com/stephenafamo/bob/tree/main/./dialect/psql/"
    click SQLiteDialect "https://github.com/stephenafamo/bob/tree/main/./dialect/sqlite/"
    click Website "https://github.com/stephenafamo/bob/tree/main/./website/"

    %% Styles
    classDef cli fill:#FFA500,stroke:#333,stroke-width:1px
    classDef core fill:#228B22,stroke:#333,stroke-width:1px
    classDef dialect fill:#1E90FF,stroke:#333,stroke-width:1px
    classDef generated fill:#9370DB,stroke:#333,stroke-width:1px
    classDef db fill:#A9A9A9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef app fill:#FFFFFF,stroke:#333,stroke-width:1px
    classDef web fill:#008080,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
