# lukasaldivia/maat-ts architecture

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

- Interactive diagram: https://gitdiagram.com/lukasaldivia/maat-ts
- Repository: https://github.com/lukasaldivia/maat-ts

## Overview

##### Project Type and Purpose
- Maat-ts is a modular TypeScript library (not a full-stack app).
- It exposes a fluent API for:
- Defining tables (`TableFactory` → `Table`)
- Building queries with filters (`FilterFactory`, `FilterCollection`, various `Filter` classes)
- Executing CRUD/search operations via a pluggable SQL adapter (`Queryable`)
- Creating aggregate functions (`AggregateFunction`).

##### File Structure
- Top-level “src” modules:
- AggregateFunction
- Filter (core + Factory + variations)
- Model
- Table (core + Factory)
- vendor (utility code)
- Key factories (`TableFactory`, `FilterFactory`) generate domain objects.
- `Model` ties a `Table` and a `Queryable` together to perform operations.
- No server, UI, or persistence layer is bundled—only the library API and its internals.

##### Core Components and Their Relationships
a. Table & TableFactory
- TableFactory.create() ⇒ Table<C, PK>
- Table encapsulates table name, columns, PK.
b. Model & Queryable
- new Model(table, connection)
- CRUD and search methods delegate to `connection.query(...)`.
c. Filter System
- FilterFactory.build(options) ⇒ Filter
- FilterCollection accumulates Filters via appendFilter()
- Variations (DateFilter, NumberFilter, TextFilter, etc.) implement specific operators.
d. AggregateFunction
- AggregateFunction.from(table) ⇒ object with .count(), .sum(), etc.
e. Vendor utilities
- e.g. getAccumulated used internally by FilterCollection or Model.

##### Architectural Patterns
- Factory Pattern: `TableFactory`, `FilterFactory`
- Fluent/Builder: `FilterCollection.appendFilter()`, chainable query options
- Strategy/Polymorphism: `Filter` variations encapsulate different SQL operators
- Dependency Injection: `Model` receives a `Queryable` adapter

## Diagram (Mermaid)

```mermaid
graph TD
    %% Swimlanes
    subgraph "Consumer Layer"
        Consumer["Consumer Code"]:::external
    end

    subgraph "Core Library"
        %% Factories
        subgraph "Factories"
            TableFactory["TableFactory"]:::factory
            FilterFactory["FilterFactory"]:::factory
        end

        %% Core Orchestrator
        Model["Model"]:::core

        %% Domain Objects
        subgraph "Domain Objects"
            Table["Table"]:::domain
            FilterCollection["FilterCollection"]:::domain
            Filter["Filter (core)"]:::domain
            FilterOptions["FilterOptions"]:::domain
            DateFilter["DateFilter"]:::domain
            NumberFilter["NumberFilter"]:::domain
            RangeFilter["RangeFilter"]:::domain
            StrictTextFilter["StrictTextFilter"]:::domain
            TextFilter["TextFilter"]:::domain
            AggregateFunction["AggregateFunction"]:::domain
            AFUtilities["AF Utilities"]:::domain
            Vendor["Vendor Utilities"]:::utility
        end
    end

    subgraph "External Layer"
        Queryable["Queryable (SQL Adapter)"]:::external
        Database["Database"]:::external
    end

    %% Connections
    Consumer -->|"TableFactory.create()"| TableFactory
    TableFactory -->|"create()"| Table

    Consumer -->|"new Model(table, queryable)"| Model
    Model -->|"prepareSearch()"| FilterCollection
    FilterFactory -->|"build()"| Filter
    FilterOptions -->|"configured by"| FilterFactory
    FilterCollection -->|"appendFilter()"| Filter
    FilterCollection -->|"uses"| DateFilter
    FilterCollection -->|"uses"| NumberFilter
    FilterCollection -->|"uses"| RangeFilter
    FilterCollection -->|"uses"| StrictTextFilter
    FilterCollection -->|"uses"| TextFilter

    Consumer -->|".count(), .sum() etc."| AggregateFunction
    AggregateFunction -->|"from(table)"| AFUtilities

    Model -->|"search()/groupedSearch() uses"| FilterCollection
    Model -->|"search()/groupedSearch() uses"| AggregateFunction

    Vendor -->|"helpers"| FilterCollection
    Vendor -->|"helpers"| Model

    Model -->|"executeQuery().query()"| Queryable
    Queryable -->|"runs SQL"| Database
    Database -->|"returns SQLResult"| Model
    Model -->|"returns data"| Consumer

    %% Click Events
    click TableFactory "https://github.com/lukasaldivia/maat-ts/blob/main/src/Table/TableFactory.ts"
    click Table "https://github.com/lukasaldivia/maat-ts/blob/main/src/Table/Table.ts"
    click Model "https://github.com/lukasaldivia/maat-ts/blob/main/src/Model/Model.ts"
    click Queryable "https://github.com/lukasaldivia/maat-ts/blob/main/src/Model/types.ts"
    click FilterFactory "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/FilterFactory.ts"
    click FilterCollection "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/FilterCollection.ts"
    click Filter "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/Filter.ts"
    click FilterOptions "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/FilterOptions.ts"
    click DateFilter "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/variations/DateFilter.ts"
    click NumberFilter "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/variations/NumberFilter.ts"
    click RangeFilter "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/variations/RangeFilter.ts"
    click StrictTextFilter "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/variations/StrictTextFilter.ts"
    click TextFilter "https://github.com/lukasaldivia/maat-ts/blob/main/src/Filter/variations/TextFilter.ts"
    click AggregateFunction "https://github.com/lukasaldivia/maat-ts/blob/main/src/AggregateFunction/AggregateFunction.ts"
    click AFUtilities "https://github.com/lukasaldivia/maat-ts/blob/main/src/AggregateFunction/AF.ts"
    click Vendor "https://github.com/lukasaldivia/maat-ts/tree/main/src/vendor"

    %% Styles
    classDef factory fill:#cce5ff,stroke:#004085,stroke-width:2px
    classDef domain fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef core fill:#fff3cd,stroke:#856404,stroke-width:2px
    classDef external fill:#e2e3e5,stroke:#818182,stroke-width:2px
    classDef utility fill:#f8d7da,stroke:#721c24,stroke-width:2px
```
