# nshaibu/pydantic-mini architecture

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

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

## Overview

##### Project Type and Purpose
- It’s a Python library/tool that provides a minimal, stdlib-only alternative to Pydantic’s BaseModel.
- Purpose: Define dataclass-style models with built-in type/value validation, custom validators, and serialization to/from JSON, dict, and CSV.

##### File Structure
- Top-level: packaging & CI files (.github/, pyproject.toml, requirements-*.txt)
- `src/pydantic_mini/`: the runtime modules:
- base.py        – core BaseModel implementation
- typing.py      – MiniAnnotated, Attrib definitions
- formatters.py  – load/dump logic for JSON, dict, CSV
- exceptions.py  – ValidationError, etc.
- utils.py       – helper functions (e.g., InitVar support)
- `tests/`: unit tests that validate functionality.

##### README for Insights
- Core flows:
a. User defines a subclass of BaseModel with annotated fields.
b. .loads() invokes formatters, then BaseModel initializer.
c. BaseModel introspects annotations, applies type checks, runs validators.
d. On success, returns model instance; on failure, raises ValidationError.
e. .dump() serializes instances via formatters.
- Extensibility via: custom field validators, class-level validate methods, default factories, InitVar hooks.

##### Main Components & Their Relationships
a. User Code (their BaseModel subclasses)
b. BaseModel Core
c. Field Metadata / Annotation Layer (MiniAnnotated & Attrib)
d. Validation Engine
e. Serialization/Deserialization Layer (formatters)
f. Exceptions Module
g. Utility Module
h. Python stdlib (dataclasses, typing, json, csv, datetime)

- User code → BaseModel (definition + instantiation)
- BaseModel → typing layer (to parse field metadata)
- BaseModel → utils (InitVar, default factories)
- BaseModel → validation engine (calls built-in & custom validators)
- Validation engine → exceptions (throws ValidationError)
- BaseModel → formatters (loads/dumps) → stdlib modules
- Tests/CI pipelines are external: they invoke package build & run unit tests.

##### Architectural Patterns & Principles
- Modular separation: core logic (base) vs metadata (typing) vs IO (formatters) vs errors (exceptions).
- Single responsibility per module.
- Dependency‐inversion: BaseModel depends on abstract Annotated metadata, not concrete validators.
- Extensibility: hook points (`validate_<field>` methods, `validate` hook, `__model_init__`).
- Stdlib‐only: no third-party dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Code
    subgraph "User Model Definitions"
        direction TB
        User["User BaseModel Subclass"]:::user
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        Base["BaseModel Core"]:::core
        Typing["Field Metadata Layer\n(MiniAnnotated & Attrib)"]:::core
        Utils["Utility Module\n(InitVar & helpers)"]:::core
        Formatters["Serialization Layer\n(JSON, dict, CSV)"]:::core
        Exceptions["Exceptions Module\n(ValidationError, etc.)"]:::core
    end

    %% Python Stdlib
    subgraph "Python Stdlib"
        direction TB
        Dataclasses["dataclasses"]:::stdlib
        TypingStd["typing"]:::stdlib
        JSONMod["json"]:::stdlib
        CSVMod["csv"]:::stdlib
        DateTime["datetime"]:::stdlib
    end

    %% CI & Packaging
    subgraph "CI & Packaging"
        direction TB
        Workflows[".github/workflows"]:::ci
        Requirements["requirements-*.txt"]:::ci
        Configs["pyproject.toml\npytest.ini\n.flake8"]:::ci
        Tests["tests/test_base.py"]:::ci
    end

    %% Connections: User to Core
    User -->|".loads()/.dump() calls"| Base

    %% Core internals
    Base -->|"parse annotations"| Typing
    Base -->|"use helpers"| Utils
    Base -->|"invoke formatters"| Formatters
    Base -->|"raise on failure"| Exceptions

    %% Formatters to stdlib
    Formatters -->|"serialize/deserialize"| JSONMod
    Formatters -->|"serialize/deserialize"| CSVMod
    Utils -->|"dataclass support"| Dataclasses
    Typing -->|"typing metadata"| TypingStd
    Formatters -->|"datetime handling"| DateTime

    %% CI & Packaging flows
    Workflows -->|runs tests| Tests
    Requirements -->|install deps| Tests
    Configs -->|configures| Tests

    %% Click Events
    click Base "https://github.com/nshaibu/pydantic-mini/blob/main/src/pydantic_mini/base.py"
    click Typing "https://github.com/nshaibu/pydantic-mini/blob/main/src/pydantic_mini/typing.py"
    click Formatters "https://github.com/nshaibu/pydantic-mini/blob/main/src/pydantic_mini/formatters.py"
    click Exceptions "https://github.com/nshaibu/pydantic-mini/blob/main/src/pydantic_mini/exceptions.py"
    click Utils "https://github.com/nshaibu/pydantic-mini/blob/main/src/pydantic_mini/utils.py"
    click Tests "https://github.com/nshaibu/pydantic-mini/blob/main/tests/test_base.py"
    click Workflows "https://github.com/nshaibu/pydantic-mini/tree/main/.github/workflows"
    click Requirements "https://github.com/nshaibu/pydantic-mini/blob/main/requirements.txt"
    click Configs "https://github.com/nshaibu/pydantic-mini/blob/main/pyproject.toml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#337ab7,color:#000;
    classDef user fill:#d4edda,stroke:#3c763d,color:#000;
    classDef stdlib fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef ci fill:#fff3cd,stroke:#856404,color:#000;
```
