# florius0/schema architecture

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

- Interactive diagram: https://gitdiagram.com/florius0/schema
- Repository: https://github.com/florius0/schema

## Overview

##### Project type and purpose
- Project type: An open-source Elixir library (Mix project) that provides a compile-time DSL for defining complex, set-theoretic schemas with validation and export capabilities.
- Purpose: Let Elixir developers declare rich data schemas (with pattern matching, constraints, type inference) via macros and extensions; validate data at compile- and run-time; and export schemas to other formats.

##### File structure
- Top-level mix files: mix.exs, mix.lock, .formatter.exs, .credo.exs, .doctor.exs
- .check/ & .github/workflows/: CI/tooling pipelines (Credo, Dialyzer, ExUnit, etc.)
- config/: application configuration (config/config.exs)
- lib/: core library code
- apix.access.ex
- ecto_like_syntax.ex
- apix.schema.* – modules under Apix.Schema namespace
- apix.schema.extensions.* – built-in extensions (core, elixir)
- test/: unit tests for core and extensions

##### Key insights from README
- DSL entrypoint: `schema` macro
- Core concepts: set-theoretic types, type inference, parameterized schemas, validations
- Extensible architecture via `Apix.Schema.Extension`
- Planned feature: exporting schemas in multiple formats

##### Main components
A. User code / Client modules
- Modules that call `use Apix.Schema` and define `schema` blocks (e.g., `Api.Data`, `Api.Error`)
B. Compile-time DSL Processor (Macro Expansion)
- `Apix.Schema` module (entrypoint)
- Parses `schema` definitions, produces an internal AST (`Apix.Schema.AST`)
C. Extension Manager
- `Apix.Schema.Extension` behaviour
- Loads built-in extensions:
- Core extension (`lib/.../core.ex`) – provides set-theoretic operations, type graph, validators
- Elixir extension (`lib/.../elixir.ex`) – maps Elixir built-in types to internal types
- Allows third-party extensions to register additional type rules or transforms
D. AST & Type Graph Processor
- `Apix.Schema.Validator` & `Apix.Schema.Core.TypeGraph`
- Builds a directed graph of type relationships, prunes unreachable nodes, enforces constraints
E. Runtime Validation & Helpers
- Generated code for runtime checks (via macros)
- `Apix.Schema.Error` and `Apix.Schema.Warning`
F. Exporter subsystem (future/maybe)
- Modules that take the AST and produce JSON, YAML, OpenAPI specs, etc.
G. CI/Tooling
- .check scripts, GitHub Actions for formatting, linting, docs, tests

##### Relationships and data flow
1) Developer writes `schema` in a client module →
2) At compile time, `Apix.Schema` macro →
3) Produces `Apix.Schema.AST` →
4) Routed through Extension Manager →
5) Core & Elixir extensions enrich AST & define type rules →
6) TypeGraph builder constructs full graph →
7) Validator runs static checks →
8) Macros emit compiled code for runtime validation →
9) (Optional) Exporter reads AST to generate external schema definitions

##### Architectural patterns and design principles
- Macro-based DSL for compile-time metaprogramming
- Plugin architecture via behaviours (extensions)
- Separation of concerns: AST modeling, type graph, validation logic
- Functional, immutable data flow between components

##### Detailed elements to capture
- `Apix.Schema` macro entrypoint
- `Apix.Schema.AST` data structures
- Extension behaviour and individual extensions
- Type graph building/pruning/validation modules
- Generated runtime validation code
- Exporter interface (if present)
- CI/tooling paths invoked by GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Modules
    subgraph "Client Modules"
        direction TB
        ApiData["Api.Data Module"]:::client
        ApiError["Api.Error Module"]:::client
    end

    %% DSL Processor
    subgraph "DSL Processor" 
        direction TB
        SchemaMacro["Apix.Schema (Macro Entry Point)"]:::dsl
    end

    %% AST Data Structures
    subgraph "AST Data Structures"
        direction TB
        AST["Apix.Schema.AST"]:::ast
        ASTMeta["Apix.Schema.AST.Meta"]:::ast
        ASTFolder["Apix.Schema.AST.*"]:::ast
    end

    %% Extension Manager
    subgraph "Extension Manager"
        direction TB
        ExtManager["Apix.Schema.Extension (Behaviour)"]:::ext
    end

    %% Extensions
    subgraph "Extensions"
        direction TB
        subgraph CoreExt["Core Extension"]
            direction TB
            CoreFile["core.ex"]:::ext
            CoreFolder["core/*.ex"]:::ext
            TypeGraphFolder["core/type_graph/*.ex"]:::ext
            CoreErrors["core/errors/*.ex"]:::ext
            CoreWarnings["core/warnings/*.ex"]:::ext
        end
        subgraph ElixirExt["Elixir Extension"]
            direction TB
            ElixirFile["elixir.ex"]:::ext
            ElixirFolder["elixir/*.ex"]:::ext
        end
    end

    %% TypeGraph & Validator
    subgraph "TypeGraph & Validator"
        direction TB
        Graph["type_graph/graph.ex"]:::coreext
        Definition["type_graph/definition.ex"]:::coreext
        Pruner["type_graph/pruner.ex"]:::coreext
        TGValidator["type_graph/validator.ex"]:::coreext
        Validator["Apix.Schema.Validator"]:::coreext
    end

    %% Runtime Validation & Helpers
    subgraph "Runtime Validation & Helpers"
        direction TB
        ErrorMod["apix.schema.error.ex"]:::runtime
        InvalidASTError["invalid_ast_error.ex"]:::runtime
        InvalidElixirASTError["invalid_elixir_ast_error.ex"]:::runtime
        WarningMod["apix.schema.warning.ex"]:::runtime
        WarningsFolder["warnings/*.ex"]:::runtime
    end

    %% Exporter (Future)
    Exporter["Exporter Subsystem (JSON/YAML/OpenAPI)"]:::dsl

    %% Application Entry
    subgraph "Application Entry"
        direction TB
        AppSupervision["apix.schema.application.ex"]:::application
    end

    %% Configuration & CI
    subgraph "Configuration & CI/Tooling"
        direction TB
        Config["config/config.exs"]:::ci
        CheckScripts[".check/"]:::ci
        CIYaml[".github/workflows/ci.yaml"]:::ci
        Credo[".credo.exs"]:::ci
        Formatter[".formatter.exs"]:::ci
        Doctor[".doctor.exs"]:::ci
    end

    %% Data Flow
    ApiData -->|"defines schema"| SchemaMacro
    ApiError -->|"defines schema"| SchemaMacro
    SchemaMacro -->|"produces AST"| AST
    AST -->|"routes through"| ExtManager
    ExtManager -->|"loads Core Extension"| CoreFile
    ExtManager -->|"loads Elixir Extension"| ElixirFile
    CoreFile -->|"enriches AST"| AST
    ElixirFile -->|"enriches AST"| AST
    AST -->|"builds graph"| Graph
    Graph --> Definition
    Definition --> Pruner
    Pruner --> TGValidator
    TGValidator --> Validator
    Validator -->|"generates runtime code"| ErrorMod
    Validator --> WarningMod
    ErrorMod --> InvalidASTError
    ErrorMod --> InvalidElixirASTError
    WarningMod --> WarningsFolder
    AST -->|"future export"| Exporter
    AppSupervision --> SchemaMacro
    Config --> SchemaMacro
    CheckScripts --> Credo
    CheckScripts --> Formatter
    CheckScripts --> Doctor
    CIYaml --> CheckScripts

    %% Click Events
    click SchemaMacro "https://github.com/florius0/schema/blob/main/lib/apix.schema.ex"
    click AST "https://github.com/florius0/schema/blob/main/lib/apix.schema/ast.ex"
    click ASTMeta "https://github.com/florius0/schema/blob/main/lib/apix.schema/ast/meta.ex"
    click ASTFolder "https://github.com/florius0/schema/tree/main/lib/apix.schema/ast/"
    click ExtManager "https://github.com/florius0/schema/blob/main/lib/apix.schema/extension.ex"
    click CoreFile "https://github.com/florius0/schema/blob/main/lib/apix.schema.extensions/core.ex"
    click CoreFolder "https://github.com/florius0/schema/tree/main/lib/apix.schema.extensions/core/"
    click TypeGraphFolder "https://github.com/florius0/schema/tree/main/lib/apix.schema.extensions/core/type_graph/"
    click CoreErrors "https://github.com/florius0/schema/tree/main/lib/apix.schema.extensions/core/errors/"
    click CoreWarnings "https://github.com/florius0/schema/tree/main/lib/apix.schema.extensions/core/warnings/"
    click ElixirFile "https://github.com/florius0/schema/blob/main/lib/apix.schema.extensions/elixir.ex"
    click ElixirFolder "https://github.com/florius0/schema/tree/main/lib/apix.schema.extensions/elixir/"
    click Graph "https://github.com/florius0/schema/blob/main/lib/apix.schema.extensions/core/type_graph/graph.ex"
    click Definition "https://github.com/florius0/schema/blob/main/lib/apix.schema.extensions/core/type_graph/definition.ex"
    click Pruner "https://github.com/florius0/schema/blob/main/lib/apix.schema.extensions/core/type_graph/pruner.ex"
    click TGValidator "https://github.com/florius0/schema/blob/main/lib/apix.schema.extensions/core/type_graph/validator.ex"
    click Validator "https://github.com/florius0/schema/blob/main/lib/apix.schema.validator.ex"
    click ErrorMod "https://github.com/florius0/schema/blob/main/lib/apix.schema/error.ex"
    click InvalidASTError "https://github.com/florius0/schema/blob/main/lib/apix.schema/errors/invalid_ast_error.ex"
    click InvalidElixirASTError "https://github.com/florius0/schema/blob/main/lib/apix.schema/errors/invalid_elixir_ast_error.ex"
    click WarningMod "https://github.com/florius0/schema/blob/main/lib/apix.schema/warning.ex"
    click WarningsFolder "https://github.com/florius0/schema/tree/main/lib/apix.schema/warnings/"
    click AppSupervision "https://github.com/florius0/schema/blob/main/lib/apix.schema/application.ex"
    click Config "https://github.com/florius0/schema/blob/main/config/config.exs"
    click CheckScripts "https://github.com/florius0/schema/tree/main/.check/"
    click CIYaml "https://github.com/florius0/schema/blob/main/.github/workflows/ci.yaml"
    click Credo "https://github.com/florius0/schema/blob/main/.credo.exs"
    click Formatter "https://github.com/florius0/schema/blob/main/.formatter.exs"
    click Doctor "https://github.com/florius0/schema/blob/main/.doctor.exs"

    %% Styles
    classDef client fill:#fee2e2,stroke:#b91c1c
    classDef dsl fill:#bfdbfe,stroke:#1e3a8a
    classDef ast fill:#dbeafe,stroke:#2563eb
    classDef ext fill:#dcfce7,stroke:#15803d
    classDef coreext fill:#dcfce7,stroke:#15803d
    classDef runtime fill:#fef3c7,stroke:#92400e
    classDef application fill:#e0f2fe,stroke:#0369a1
    classDef ci fill:#f3f4f6,stroke:#4b5563
```
