# nshaibu/formax architecture

> Architecture diagram of the GitHub repository nshaibu/formax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nshaibu/formax
- Repository: https://github.com/nshaibu/formax

## Overview

Formax is a Python model-building and validation library. A developer declares a BaseModel schema; class construction prepares configured fields and hooks, then model initialization applies formatting and validation before storing values or raising errors. Models can also encode and decode dict, JSON, and CSV data through registered formatters. The graph reflects the README’s documented features; unsampled runtime modules are included only where their paths and responsibilities are clear from the tree.

Main entry points: [`src/formax/base.py`](https://github.com/nshaibu/formax/blob/main/src/formax/base.py) (BaseModel), [`src/formax/fields.py`](https://github.com/nshaibu/formax/blob/main/src/formax/fields.py) (Field descriptors), [`src/formax/make_init.py`](https://github.com/nshaibu/formax/blob/main/src/formax/make_init.py) (Init strategies), [`src/formax/formatters.py`](https://github.com/nshaibu/formax/blob/main/src/formax/formatters.py) (Formatters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_schema["Schema construction"]
  node_model["BaseModel<br/>[base.py]"]
  node_config["Model configuration<br/>[typing.py]"]
  node_fieldmeta["Field metadata<br/>[typing.py]"]
  node_hooks["Hook decorators<br/>[decorators.py]"]
end

subgraph group_runtime["Model runtime"]
  node_initgen["Init strategies<br/>[make_init.py]"]
  node_fields["Field descriptors<br/>[fields.py]"]
  node_fastfuncs["Optimized setters<br/>[optimised_funcs.py]"]
end

subgraph group_validation["Validation and typing"]
  node_typing["Type resolution<br/>[typing.py]"]
  node_constraints["Type and constraints<br/>[fields.py]"]
  node_callbacks["Custom callbacks<br/>[base.py]"]
end

subgraph group_formatting["Formatting and errors"]
  node_errors["Validation errors<br/>[exceptions.py]"]
  node_errorutils["Error processing<br/>[utils.py]"]
  node_formatters["Formatters<br/>[formatters.py]"]
end

node_developer(("Developer"))
node_result["Model or data"]

node_developer -->|"declares schema"| node_model
node_model -->|"reads config"| node_config
node_model -->|"prepares fields"| node_fieldmeta
node_model -->|"collects hooks"| node_hooks
node_model -->|"selects initializer"| node_initgen
node_model -->|"installs descriptors"| node_fields
node_model -->|"resolves annotations"| node_typing
node_initgen -->|"initializes fields"| node_fields
node_initgen -->|"uses optimized functions"| node_fastfuncs
node_fields -->|"validates values"| node_constraints
node_fields -->|"runs field hooks"| node_callbacks
node_fields -->|"processes failures"| node_errorutils
node_errorutils -->|"collects or raises"| node_errors
node_fields -->|"stores field values"| node_result
node_developer -->|"requests conversion"| node_formatters
node_formatters -->|"coerces input"| node_fields
node_formatters -->|"encodes or decodes"| node_result

click node_model "https://github.com/nshaibu/formax/blob/main/src/formax/base.py"
click node_config "https://github.com/nshaibu/formax/blob/main/src/formax/typing.py"
click node_fieldmeta "https://github.com/nshaibu/formax/blob/main/src/formax/typing.py"
click node_hooks "https://github.com/nshaibu/formax/blob/main/src/formax/decorators.py"
click node_initgen "https://github.com/nshaibu/formax/blob/main/src/formax/make_init.py"
click node_fields "https://github.com/nshaibu/formax/blob/main/src/formax/fields.py"
click node_fastfuncs "https://github.com/nshaibu/formax/blob/main/src/formax/optimised_funcs.py"
click node_typing "https://github.com/nshaibu/formax/blob/main/src/formax/typing.py"
click node_constraints "https://github.com/nshaibu/formax/blob/main/src/formax/fields.py"
click node_callbacks "https://github.com/nshaibu/formax/blob/main/src/formax/base.py"
click node_errors "https://github.com/nshaibu/formax/blob/main/src/formax/exceptions.py"
click node_errorutils "https://github.com/nshaibu/formax/blob/main/src/formax/utils.py"
click node_formatters "https://github.com/nshaibu/formax/blob/main/src/formax/formatters.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_model,node_config,node_fieldmeta,node_hooks toneBlue
class node_initgen,node_fields,node_fastfuncs toneAmber
class node_typing,node_constraints,node_callbacks toneMint
class node_errors,node_errorutils,node_formatters toneRose
class node_developer,node_result toneIndigo
```

## Components

### Schema construction

- [BaseModel](https://github.com/nshaibu/formax/blob/main/src/formax/base.py): `src/formax/base.py`
- [Model configuration](https://github.com/nshaibu/formax/blob/main/src/formax/typing.py): `src/formax/typing.py`
- [Field metadata](https://github.com/nshaibu/formax/blob/main/src/formax/typing.py): `src/formax/typing.py`
- [Hook decorators](https://github.com/nshaibu/formax/blob/main/src/formax/decorators.py): `src/formax/decorators.py`

### Model runtime

- [Init strategies](https://github.com/nshaibu/formax/blob/main/src/formax/make_init.py): `src/formax/make_init.py`
- [Field descriptors](https://github.com/nshaibu/formax/blob/main/src/formax/fields.py): `src/formax/fields.py`
- [Optimized setters](https://github.com/nshaibu/formax/blob/main/src/formax/optimised_funcs.py): `src/formax/optimised_funcs.py`

### Validation and typing

- [Type resolution](https://github.com/nshaibu/formax/blob/main/src/formax/typing.py): `src/formax/typing.py`
- [Type and constraints](https://github.com/nshaibu/formax/blob/main/src/formax/fields.py): `src/formax/fields.py`
- [Custom callbacks](https://github.com/nshaibu/formax/blob/main/src/formax/base.py): `src/formax/base.py`

### Formatting and errors

- [Validation errors](https://github.com/nshaibu/formax/blob/main/src/formax/exceptions.py): `src/formax/exceptions.py`
- [Error processing](https://github.com/nshaibu/formax/blob/main/src/formax/utils.py): `src/formax/utils.py`
- [Formatters](https://github.com/nshaibu/formax/blob/main/src/formax/formatters.py): `src/formax/formatters.py`

### Other components

- **Developer**
- **Model or data**

## Connections

- Developer → BaseModel: declares schema
- BaseModel → Model configuration: reads config
- BaseModel → Field metadata: prepares fields
- BaseModel → Hook decorators: collects hooks
- BaseModel → Init strategies: selects initializer
- BaseModel → Field descriptors: installs descriptors
- BaseModel → Type resolution: resolves annotations
- Init strategies → Field descriptors: initializes fields
- Init strategies → Optimized setters: uses optimized functions
- Field descriptors → Type and constraints: validates values
- Field descriptors → Custom callbacks: runs field hooks
- Field descriptors → Error processing: processes failures
- Error processing → Validation errors: collects or raises
- Field descriptors → Model or data: stores field values
- Developer → Formatters: requests conversion
- Formatters → Field descriptors: coerces input
- Formatters → Model or data: encodes or decodes