# vst/postmap architecture

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

- Interactive diagram: https://gitdiagram.com/vst/postmap
- Repository: https://github.com/vst/postmap

## Overview

##### Main Components
- Application Entry Point: The executable located in the “app” directory (app/Main.hs) represents the CLI entry point that a user interacts with.
- Core Library Modules:
- The “Postmap” module in the “src/Postmap” directory is the heart of the introspection and code generation process. Within this, you have:
∘ CLI support (e.g. src/Postmap/Cli.hs) for handling command-line arguments.
∘ Database Introspection Components (inside src/Postmap/Database and its submodules): This subcomponent handles reading the database schema, constraints, names, and structures.
∘ Code Generation components (src/Postmap/Codegen/Haskell and submodules): Responsible for translating the introspected schema into Haskell code, using patterns and overriding settings.
∘ A “Meta” submodule (src/Postmap/Meta.hs) for potentially coordinating and managing higher-level logic.
- Build and Configuration Tools: The project uses a variety of build scripts and configuration files:
- Haskell build configuration files (cabal.project, package.yaml, .ghci, etc.).
- Nix-related files (default.nix, shell.nix, and the nix/lib submodules) that build reproducible development and deployment environments.
- Formatting, linting, and testing configurations (fourmolu, hlint, doctest, and spec folders).

##### Relationships and Data Flow
- The CLI component (from “app/Main.hs” and “src/Postmap/Cli.hs”) serves as the entry point and passes user parameters into the workflow.
- The Database Interaction module (from “src/Postmap/Database”) is invoked to introspect the PostgreSQL database, extract schemas, constraints, and references.
- The Code Generation engine (under “src/Postmap/Codegen/Haskell”) takes the data provided by introspection, processes it, and produces Haskell code that maps to the database schema.
- The Zamazingo utilities may be called upon during both introspection (for parsing or formatting) and code generation (for mapping data types and JSON serialization).

##### Architectural Patterns and Design Principles
- Modularity and Separation of Concerns: The project is separated into distinct modules (CLI, DB introspection, code generation, helper utilities), ensuring each responsibility is encapsulated.
- Layered Architecture: Data flows from the user input via CLI to the database introspection layer and then moves into the code generation layer, all while being supported by shared utility functions.
- Infrastructure-as-Code elements: The use of Nix configuration for development environments shows a clear separation between development tooling and application logic.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Application Entry
    subgraph "Application Entry"
        A["CLI / Main Application"]:::cli
    end

    %% Core Library: Postmap
    subgraph "Core Library (Postmap)"
        B["CLI Support Module"]:::core
        subgraph "Database Introspection"
            DB["Database Introspection (Module)"]:::db
            D["Introspect"]:::db
            E["Constraints"]:::db
            F["Names"]:::db
            G["Reference"]:::db
            H["Structure"]:::db
            I["Types"]:::db
        end
        subgraph "Code Generation Engine (Haskell)"
            CE["Code Generation (Module)"]:::codegen
            K["Common"]:::codegen
            L["Overriding"]:::codegen
            M["Rel8"]:::codegen
        end
        N["Meta Module"]:::meta
    end

    %% Utility Components: Zamazingo
    subgraph "Utility Components (Zamazingo)"
        U["Zamazingo (Module)"]:::utility
        U1["Aeson"]:::utility
        U2["Autodocodec"]:::utility
        U3["D2"]:::utility
        U4["Text"]:::utility
    end

    %% Build & Configuration Tools
    subgraph "Build & Configuration Tools"
        Build["Haskell Build Config"]:::build
        Nix["Nix Configurations"]:::build
        Test["Formatting_Linting_Testing"]:::build
    end

    %% Data Flow Connections
    A -->|"triggers"| B
    B -->|"invokes"| DB
    DB -->|"extracts_schema"| D
    DB -->|"reads_constraints"| E
    DB -->|"fetches_names"| F
    DB -->|"resolves_references"| G
    DB -->|"structures_schema"| H
    DB -->|"maps_types"| I
    DB -->|"passes_schema"| CE
    CE -->|"generates_code"| K
    CE -->|"applies_overrides"| L
    CE -->|"handles_Rel8"| M
    N ---|"coordinates"| DB
    N ---|"coordinates"| CE
    U ---|"supports"| DB
    U ---|"supports"| CE
    Build ---|"builds"| B
    Nix ---|"configures"| B
    Test ---|"validates"| B

    %% Styling Classes
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef db fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef codegen fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef meta fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef utility fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events for Application Entry & Core Library
    click A "https://github.com/vst/postmap/blob/main/app/Main.hs"
    click B "https://github.com/vst/postmap/blob/main/src/Postmap/Cli.hs"
    
    %% Click Events for Database Introspection Components
    click DB "https://github.com/vst/postmap/tree/main/src/Postmap/Database"
    click D "https://github.com/vst/postmap/blob/main/src/Postmap/Database/Introspect.hs"
    click E "https://github.com/vst/postmap/blob/main/src/Postmap/Database/Constraints.hs"
    click F "https://github.com/vst/postmap/blob/main/src/Postmap/Database/Names.hs"
    click G "https://github.com/vst/postmap/blob/main/src/Postmap/Database/Reference.hs"
    click H "https://github.com/vst/postmap/blob/main/src/Postmap/Database/Structure.hs"
    click I "https://github.com/vst/postmap/blob/main/src/Postmap/Database/Types.hs"
    
    %% Click Events for Code Generation Engine Components
    click CE "https://github.com/vst/postmap/tree/main/src/Postmap/Codegen/Haskell"
    click K "https://github.com/vst/postmap/blob/main/src/Postmap/Codegen/Haskell/Common.hs"
    click L "https://github.com/vst/postmap/blob/main/src/Postmap/Codegen/Haskell/Overriding.hs"
    click M "https://github.com/vst/postmap/blob/main/src/Postmap/Codegen/Haskell/Rel8.hs"
    
    %% Click Event for Meta Module
    click N "https://github.com/vst/postmap/blob/main/src/Postmap/Meta.hs"
    
    %% Click Events for Utility Components (Zamazingo)
    click U "https://github.com/vst/postmap/tree/main/src/Zamazingo"
    click U1 "https://github.com/vst/postmap/blob/main/src/Zamazingo/Aeson.hs"
    click U2 "https://github.com/vst/postmap/blob/main/src/Zamazingo/Autodocodec.hs"
    click U3 "https://github.com/vst/postmap/blob/main/src/Zamazingo/D2.hs"
    click U4 "https://github.com/vst/postmap/blob/main/src/Zamazingo/Text.hs"
    
    %% Click Events for Build & Configuration Tools
    click Build "https://github.com/vst/postmap/blob/main/cabal.project"
    click Nix "https://github.com/vst/postmap/blob/main/default.nix"
    click Test "https://github.com/vst/postmap/blob/main/fourmolu.yaml"
```
