# netherlandsforensicinstitute/confidence architecture

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

- Interactive diagram: https://gitdiagram.com/netherlandsforensicinstitute/confidence
- Repository: https://github.com/netherlandsforensicinstitute/confidence

## Overview

##### Project type and purpose
- It’s a Python configuration library (not a web or full-stack app).
- Purpose: load settings from YAML/JSON files, environment variables, default dicts, apply precedence, expose a read-only dict-like object with namespace support and value references.

##### File structure
Top-level directories and files:
- confidence/ – main package
– io.py   (file and loader interfaces)
– models.py   (Configuration class, namespace, resolution logic)
– utils.py   (helpers: merging, precedence, reference resolution)
– exceptions.py   (error classes)
- tests/ – unit tests covering each module
- docs/ – Sphinx docs (usage guides, API reference)
- .github/workflows – CI (tests & releases)
- pyproject.toml & pdm.lock – build & dependency config

##### Extract insights from the README
- Entry-point functions: loadf(), load_name(), Configuration(...) constructor.
- Features: multi-file loading, built-in load order (system vs. user), environment variable mapping, references, namespaces.
- Extensibility: users can plug in custom loaders or supply raw dicts.

##### Main components
A. Adapters / Input Sources
- File loaders (YAML, JSON) – in io.py
- Environment loader – built into loaders in io.py
- Literal dicts or custom sources – user-provided
B. Loader Registry & Precedence Engine
- loader chain orchestrator (defines load order, skips missing)
- implements Locality enum, loaders(...) factory
C. Merge & Resolution Core
- utils.merge / precedence logic – merges multiple maps in correct order
- reference resolver – replaces ${foo.bar} placeholders
D. Data Model
- Configuration class (models.py)
– wraps merged data
– implements attribute access, get(), namespaces, NotConfigured sentinel
E. Exception Handling
- exceptions.py – Invalid paths, circular references, loader failures
F. Consumer / Client
- Application code calling loadf(), load_name(), consuming Configuration API

##### Relationships & data flow
1) Client calls loadf() or load_name()
2) Input Sources → Adapter modules produce raw dicts
3) Loader Registry sequences these adapters based on precedence
4) Precedence Engine merges dicts into a single map
5) Reference Resolver walks the map, interpolates values
6) Configuration object is instantiated with final map
7) Client code queries Configuration via .get(), attribute access, or **kwargs unpacking

##### Architectural patterns
- Adapter pattern for source loaders
- Pipeline (chain of responsibility) for merging and resolution
- Facade (Configuration class exposes a simple API over internals)
- Sentinel (NotConfigured) for missing values

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Adapters Layer
    subgraph "Adapters / Input Sources"
        direction TB
        FileLoader["YAML/JSON Loader"]:::adapters
        EnvLoader["Environment Loader"]:::adapters
        CustomLoader["Custom/User Dict Loader"]:::adapters
    end

    %% Loader Registry & Precedence Engine
    subgraph "Loader Registry & Precedence Engine"
        direction TB
        Registry["Loader Registry & Precedence Engine"]:::adapters
    end

    %% Merge & Resolution Core
    subgraph "Merge & Resolution Core"
        direction TB
        Merge["merge() & Precedence Logic"]:::core
        Resolver["Reference Resolver"]:::core
    end

    %% Data Model & API
    subgraph "Data Model & Facade"
        direction TB
        ConfigClass["Configuration Class"]:::model
    end

    %% Exception Handling
    Exception["Exceptions"]:::exceptions

    %% Client / Consumer
    Client["Client / Consumer\n(loadf(), load_name(), Configuration())"]:::client

    %% Data Flow
    Client -->|"calls loadf()/load_name()"| Registry
    Registry -->|"invoke adapters"| FileLoader
    Registry -->|"invoke adapters"| EnvLoader
    Registry -->|"invoke adapters"| CustomLoader
    FileLoader -->|"raw dict"| Registry
    EnvLoader -->|"raw dict"| Registry
    CustomLoader -->|"raw dict"| Registry
    Registry -->|"collect raw dicts"| Merge
    Merge -->|"merged map"| Resolver
    Resolver -->|"resolved map"| ConfigClass
    ConfigClass -->|"returns Configuration object"| Client

    %% Exception Paths
    FileLoader -.->|on error| Exception
    EnvLoader -.->|on error| Exception
    CustomLoader -.->|on error| Exception
    Registry -.->|skip missing / loader failures| Exception
    Merge -.->|on conflict| Exception
    Resolver -.->|on circular reference| Exception
    ConfigClass -.->|invalid access| Exception

    %% Click Events
    click FileLoader "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/io.py"
    click EnvLoader "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/io.py"
    click CustomLoader "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/io.py"
    click Registry "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/io.py"
    click Merge "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/utils.py"
    click Resolver "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/utils.py"
    click ConfigClass "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/models.py"
    click Exception "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/exceptions.py"
    click Client "https://github.com/netherlandsforensicinstitute/confidence/blob/main/confidence/__init__.py"

    %% Styles
    classDef adapters fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef core fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef model fill:#FFF4DD,stroke:#FFA500,color:#FFA500;
    classDef exceptions fill:#FFE0E0,stroke:#d32f2f,color:#d32f2f;
    classDef client fill:#F0F0F0,stroke:#888888,color:#333333Conference
```
