# sequelize/sequelize-auto architecture

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

- Interactive diagram: https://gitdiagram.com/sequelize/sequelize-auto
- Repository: https://github.com/sequelize/sequelize-auto

## Overview

##### Project Type and Purpose
- This is an open-source CLI and library tool (“Sequelize-Auto”) written in TypeScript/JavaScript.
- Purpose: connect to an existing SQL database, inspect its schema (tables, columns, foreign keys, indexes), and automatically generate Sequelize model definitions and an initialization file.

##### Core Architectural Components
a. Entry Points
- bin/sequelize-auto (CLI wrapper)
- index.js (programmatic require() entry)
b. Configuration Loader
- Reads CLI args or JSON config (sample.env, config.json, sample/config.js)
- Normalizes options (dialect, host, database, output dir, naming cases, tables to include/skip)
c. Database Connector
- Uses Sequelize (external library) and dialect bindings (mysql2, pg, sqlite3, tedious)
- src/dialects/* implements per-dialect query logic and type mapping
d. Core Modules (in src/)
- auto-generator.ts – orchestrates the full generation flow
- auto-builder.ts – builds in-memory metadata structures (tables, columns, associations)
- auto-relater.ts – discovers foreign key relationships and builds association maps
- auto-writer.ts – renders the model files and init-models file to disk or text
e. Output
- Model files (ES5/ES6/ESM/TS) in specified output directory
- init-models.(js|ts) file that imports all models and establishes associations
f. Sample App & Tests
- sample/ directory with demo scripts, db scripts, example TS/JS usage
- test/ directory with unit tests validating each module’s behavior

##### Interactions and Data Flow
1. User invokes CLI or loads programmatic API
2. Configuration Loader parses options → passes to auto-generator
3. auto-generator instantiates Sequelize instance with proper dialect binding
4. auto-generator queries database schema via Sequelize + dialect modules
5. auto-builder constructs metadata objects for each table/column
6. auto-relater analyzes foreign keys and builds association definitions
7. auto-writer renders templates for each model file + init-models file
8. Files are written to disk (or returned as text if --noWrite)
9. Downstream: Developer code imports generated models → calls initModels(sequelize) → can immediately use Sequelize ORM

##### Architectural Patterns & Design Principles
- Modular separation: parsing/config, introspection, metadata building, relationship mapping, file writing
- Strategy pattern for dialects: src/dialects/* encapsulates dialect-specific SQL and type mapping
- Pluggable output formats: writer supports multiple languages & module formats (ES5, ES6, ESM, TS)
- Single Responsibility: each auto-*.ts file has a clear role in the pipeline
- Test-driven: test/ modules validate each pipeline stage

##### Essential Elements
- Clear labels on each module/component (e.g., “auto-relater.ts”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    CLI["CLI: bin/sequelize-auto"]:::entry
    API["Programmatic API"]:::entry

    %% Core Modules
    subgraph "Core Pipeline"
        CFG["Configuration Loader"]:::core
        GEN["auto-generator.ts"]:::core
        BLD["auto-builder.ts"]:::core
        RLT["auto-relater.ts"]:::core
        WRT["auto-writer.ts"]:::core
    end

    %% Dialect Strategy Modules
    subgraph "Dialect Strategies"
        MS["mssql.ts"]:::core
        MY["mysql.ts"]:::core
        PG["postgres.ts"]:::core
        SQ["sqlite.ts"]:::core
        DIAL["dialects.ts"]:::core
        OPT["dialect-options.ts"]:::core
    end

    %% External Systems
    DB[(Database)]:::external
    SQL["Sequelize Library"]:::external
    FS["File System"]:::external

    %% Artifacts
    subgraph "Validation & Samples"
        SAMP["sample/"]:::artifact
        TEST["test/"]:::artifact
    end

    %% Generated Output
    GM["Generated Model Files\n(init-models.js/ts)"]:::artifact

    %% Data Flow
    CLI -->|"invokes"| CFG
    API -->|"loads API"| CFG
    CFG -->|"Options object"| GEN
    GEN -->|"instantiates Sequelize"| SQL
    GEN -->|"queries schema"| DB
    GEN -->|"passes schema metadata"| BLD
    BLD -->|"metadata objects"| RLT
    RLT -->|"association definitions"| WRT
    WRT -->|"renders code"| GM
    WRT -->|"writes files"| FS
    GM -->|"consume by "| SQL

    %% Dialect integration
    GEN -->|"strategy binding"| MS
    GEN -->|"strategy binding"| MY
    GEN -->|"strategy binding"| PG
    GEN -->|"strategy binding"| SQ
    GEN -->|"loads"| DIAL
    GEN -->|"loads"| OPT

    %% Samples & Tests
    CFG -->|"demo config"| SAMP
    GEN -->|"sample generation"| SAMP
    SAMP -->|"run tests"| TEST

    %% Click Events
    click CLI "https://github.com/sequelize/sequelize-auto/tree/master/bin/sequelize-auto"
    click API "https://github.com/sequelize/sequelize-auto/blob/master/index.js"
    click API "https://github.com/sequelize/sequelize-auto/blob/master/src/index.ts"
    click CFG "https://github.com/sequelize/sequelize-auto/blob/master/src/auto.ts"
    click GEN "https://github.com/sequelize/sequelize-auto/blob/master/src/auto-generator.ts"
    click BLD "https://github.com/sequelize/sequelize-auto/blob/master/src/auto-builder.ts"
    click RLT "https://github.com/sequelize/sequelize-auto/blob/master/src/auto-relater.ts"
    click WRT "https://github.com/sequelize/sequelize-auto/blob/master/src/auto-writer.ts"
    click MS "https://github.com/sequelize/sequelize-auto/blob/master/src/dialects/mssql.ts"
    click MY "https://github.com/sequelize/sequelize-auto/blob/master/src/dialects/mysql.ts"
    click PG "https://github.com/sequelize/sequelize-auto/blob/master/src/dialects/postgres.ts"
    click SQ "https://github.com/sequelize/sequelize-auto/blob/master/src/dialects/sqlite.ts"
    click DIAL "https://github.com/sequelize/sequelize-auto/blob/master/src/dialects/dialects.ts"
    click OPT "https://github.com/sequelize/sequelize-auto/blob/master/src/dialects/dialect-options.ts"
    click SAMP "https://github.com/sequelize/sequelize-auto/tree/master/sample/"
    click TEST "https://github.com/sequelize/sequelize-auto/tree/master/test/"

    %% Styles
    classDef entry fill:#e0f9b5,stroke:#333,stroke-width:1
    classDef core fill:#bfdfff,stroke:#333,stroke-width:1
    classDef external fill:#ffd0b5,stroke:#333,stroke-width:1
    classDef artifact fill:#f0f0f0,stroke:#333,stroke-width:1
```
