# billuc/cigogne architecture

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

- Interactive diagram: https://gitdiagram.com/billuc/cigogne
- Repository: https://github.com/billuc/cigogne

## Overview

##### Project type and purpose
- This is an open-source CLI tool and library (not a full-stack app) written in Gleam that manages Postgres database migrations. It reads SQL files from disk, parses “up”/“down” sections, and applies or rolls back migrations against a Postgres database, tracking applied migrations (with hashes) and updating a local schema file.

##### File structure
- Top level:
- src/cigogne.gleam – CLI entrypoint module, exposes commands (up, down, last, apply, show, new, to_v3).
- src/cigogne/internal/ – four responsibility-driven modules:
– database.gleam: Connects to Postgres, runs SQL, reads/writes migrations history table.
– fs.gleam: Reads the migrations directory (`priv/migrations`), reads/writes schema file.
– migrations.gleam: Parses `.sql` files into up/down statements.
– utils.gleam: Common helpers (hashing, error formatting).
- src/cigogne/to_v3.gleam – migration helper for upgrading older migration formats to v3.
- src/cigogne/types.gleam – core data types (Migration, Query, etc.).
- Tests mirror the internal modules, confirming separation of concerns.

##### README insights
- Commands are invoked via `gleam run -m cigogne <command>`.
- Environment: reads `DATABASE_URL`.
- Workflow: read `.sql` files named `<timestamp>-<name>.sql`, split sections by `--- migration:up/down/end`, apply to DB, record hashes, update schema file.
- Integrates well with squirrel (a SQL builder).

1. CLI Entrypoint (cigogne.gleam)
2. Configuration Loader (reads env var, CLI args)
3. Migration Service / Manager (core orchestrator)
4. File System Module (fs)
5. Parser Module (migrations)
6. Database Module (database)
7. Schema File Updater (also fs)
8. Hash & Utils Module (utils)
9. Legacy Script (to_v3)
10. External Systems: Postgres DB, Local Filesystem, Environment Variables

- CLI → Configuration Loader: “parse command & options”
- Configuration Loader → Migration Service: “command + config”
- Migration Service → File System Module: “list & read .sql files”
- File System → Parser Module: “raw SQL text”
- Parser → Migration Service: “up/down queries list”
- Migration Service → Database Module: “execute SQL batch”
- Database Module ↔ Postgres: “SQL over TCP”
- Database Module → Utils: “compute/check hash”
- Migration Service → Schema File Updater: “write updated schema file”
- Migration Service → CLI: “return result or error”
- CLI → stdout/stderr: “display status or errors”
- CLI → Legacy Script (to_v3): “if invoked”

c. Architectural patterns & principles
- Layered architecture:
- Presentation/CLI layer
- Service/Orchestration layer (Migration Service)
- Data Access layers (File System & DB modules)
- Single-Responsibility modules (internal/internal)
- Dependency injection of DB connection into Migration Service
- Extensibility point: adding new commands or file formats (to_v3)

d. Key technologies & frameworks
- Gleam (language & build)
- Postgres (external DB)
- Squirrel (optional SQL builder integration)
- File I/O via Gleam’s fs module
- CLI via `gleam run -m`

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        CLI["CLI Entrypoint"]:::blue
        Config["Configuration Loader"]:::blue
    end

    subgraph "Orchestration Layer"
        Service["Migration Service"]:::green
        Types["Core Data Types"]:::green
        Legacy["Legacy Migration Helper"]:::green
    end

    subgraph "I/O Layer"
        FS["File System Module"]:::yellow
        Parser["Parser Module"]:::yellow
        SchemaUpdater["Schema File Updater"]:::yellow
        DB["Database Module"]:::yellow
    end

    subgraph "External Systems"
        Env["Environment Variables"]:::orange
        MigrationsFolder["priv/migrations\n(SQL files)"]:::orange
        SchemaFile["schema file"]:::orange
        Postgres[(Postgres DB)]:::orange
        StdOut["stdout/stderr"]:::orange
    end

    Env -->|"readDATABASE_URL"|Config
    CLI -->|"parsecommand&options"|Config
    Config -->|"command+config"|Service
    Service -->|"list&read.sqlfiles"|FS
    MigrationsFolder -->|"contains.sqlfiles"|FS
    FS -->|"rawSQLtext"|Parser
    Parser -->|"up/downquerieslist"|Service
    Service -->|"executeSQLbatch"|DB
    DB -->|"SQLoverTCP"|Postgres
    DB -->|"compute/checkhash"|Utils
    Service -->|"writeupdatedschemafile"|SchemaUpdater
    SchemaUpdater -->|"writefile"|SchemaFile
    Service -->|"returnresult/error"|CLI
    CLI -->|"displaystatus/errors"|StdOut
    CLI -->|"ifinvoked"|Legacy
    Service -.->|"errorflow"|Utils
    Utils -->|"formaterror"|CLI

    classDef blue fill:#cce5ff,stroke:#003366,color:#003366;
    classDef green fill:#d4edda,stroke:#155724,color:#155724;
    classDef yellow fill:#fff3cd,stroke:#856404,color:#856404;
    classDef orange fill:#f8d7da,stroke:#721c24,color:#721c24;

    click CLI "https://github.com/billuc/cigogne/blob/main/src/cigogne.gleam"
    click Config "https://github.com/billuc/cigogne/blob/main/src/cigogne.gleam"
    click Service "https://github.com/billuc/cigogne/blob/main/src/cigogne.gleam"
    click FS "https://github.com/billuc/cigogne/blob/main/src/cigogne/internal/fs.gleam"
    click SchemaUpdater "https://github.com/billuc/cigogne/blob/main/src/cigogne/internal/fs.gleam"
    click Parser "https://github.com/billuc/cigogne/blob/main/src/cigogne/internal/migrations.gleam"
    click DB "https://github.com/billuc/cigogne/blob/main/src/cigogne/internal/database.gleam"
    click Utils "https://github.com/billuc/cigogne/blob/main/src/cigogne/internal/utils.gleam"
    click Legacy "https://github.com/billuc/cigogne/blob/main/src/cigogne/to_v3.gleam"
    click Types "https://github.com/billuc/cigogne/blob/main/src/cigogne/types.gleam"
```
