# goosz/modz architecture

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

- Interactive diagram: https://gitdiagram.com/goosz/modz
- Repository: https://github.com/goosz/modz

## Overview

This repo is a **Go library/framework** (not an app) that provides a **modular, type-safe dependency injection (DI) / composition system**.

From the README and file tree, the core responsibilities are:
- Build an **application/module dependency graph**
- Enforce **uniqueness and type-safety** for shared “Data” contracts
- Provide a controlled configuration API (`Binder`) for modules to declare:
- what they **consume**
- what they **produce**
- Validate configuration early (duplicate modules, duplicate producers, data key clashes, etc.)

##### Core runtime / composition
- `assembly.go` (+ `assembly_test.go`)
- Represents the **top-level orchestrator**: install modules, run configuration, finalize graph/registry, produce ready-to-use wired outputs.
- `module.go` (+ tests)
- Defines the **Module abstraction**: identity/signature, produced/consumed declarations, configuration hooks.
- `binder.go` (+ tests)
- Defines the **controlled interface** a module uses during configuration to:
- declare “I provide Data[T]”
- request “I need Data[U]”
- bind providers/values/factories (whatever the API supports)

##### Type-safe data contracts / keys
- `data.go` (+ tests, `mock_data_test.go`)
- Defines **Data[T]**: typed key/contract for cross-module sharing.
- `data_registry.go` (+ tests)
- Central **Data Registry**:
- maps Data keys -> producer(s)
- checks duplicates
- checks signature clashes
- likely used by `Assembly` during validation/finalization

##### Resolution / graph linking layer
- `binder.go` + `assembly.go` + `data_registry.go` are the “wiring triangle”.
- `binder.go` is the “write-only configuration surface” from the module’s perspective.
- `assembly.go` is the orchestrator that owns the lifecycle.
- `data_registry.go` is the authoritative record of keys/producers.

##### Errors & docs
- `errors.go` — error types that represent validation failures (these are important “outputs” of the system)
- `doc.go` — package docs (useful to confirm public mental model)

##### Non-runtime / engineering system
- `.github/workflows/*`, `.pre-commit-config.yaml`, `codecov.yml`, `SECURITY.md`, etc. (CI/quality, not runtime framework architecture)

##### Public API surface (what consumers call)
- **User Application**
- installs modules into assembly
- **Assembly API**
- **Module API**
- **Binder API**
- **Data[T] API**

##### Internal framework core (what actually runs)
- **Assembly Engine**
- module installation
- module signature uniqueness enforcement
- lifecycle: configure -> validate -> finalize
- **Module Registry**
- module signatures (package path + module name)
- singleton handling (marker interface mentioned in README)
- **Data Registry**
- Data key signatures
- producer uniqueness checks
- cross-package clash detection
- **Graph/Dependency Resolver**
- builds the dependency graph edges: “Module A consumes Data[X] produced by Module B”
- detects missing producers / cycles (if supported; if not, still show as a potential validation stage)
- **Validation & Error Model**
- emits typed errors from `errors.go`

*(Even if some of these are implemented together today, diagramming them as distinct components is useful and matches your “separate into as many components as possible” constraint.)*

- User Application
- Assembly
- Modules (N)
- Binder (per-module view; effectively created/owned by Assembly)
- Data[T] keys (declared at package level)
- Data Registry (central)
- Module Registry / Signatures
- Errors

- User Application → Assembly: `Install(Module)` / `Build()` / `Assemble()` (whatever API)
- Assembly → Module Registry: register module signatures, enforce uniqueness & singleton policy
- Assembly → Module: invoke module configuration entrypoint(s)
- Module → Binder: declare consumes/produces bindings
- Binder → Data Registry: register produced keys, request consumed keys, check duplicates/clashes
- Assembly ↔ Data Registry: during final validation/finalization
- Assembly → Errors: returns structured validation errors to the user

**Key note to encode explicitly**
- Modules **never** mutate registry directly; they only see `Binder`.
- Data keys are **package-level declarations** (README says validation checks this). Show that Data keys are created in module packages and referenced in configuration.

Lifeline list:
- User App
- Assembly
- Module A
- Module B
- Binder
- Data Registry
- Module Registry

Sequence (high-level):
##### User App → Assembly: install Module A / Module B
3. Assembly → Module Registry: compute signature (pkg path + name), enforce uniqueness / singleton rule

##### Architectural patterns/principles to call out
These are important labels/annotations in your drawing:
- **Inversion of Control / Dependency Injection**: modules declare needs; framework wires.
- **Type-safe keys** via generics (`Data[T]`): compile-time type contract.
- **Controlled configuration surface** (`Binder`): prevents modules from doing arbitrary global mutation.
- **Two-phase build**:
- *configuration collection* (modules declare)
- *validation + finalization* (assembly verifies uniqueness/clashes)
- **Identity & uniqueness via signatures**:
- module identity = package path + module name
- data key identity = signature (with clash detection)

##### Technologies/frameworks to label
- Language: **Go**
- Key language feature: **Generics** (implied by type-safe `Data`)
- Package style: single library module (`go.mod`)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% DI / Composition Framework (Go library)
%% =========================

UApp["User Application\n(Go consumer code)"]:::user

subgraph "User Space (Consumer Repo)"
  direction TB
  UMods["User Modules (N)\nModule A / Module B / ..."]:::user
  UDataKeys["Typed Data Keys\nData[T] declared in module packages"]:::user
end

subgraph "Public Framework API Surface"
  direction TB
  APIAssembly["Assembly API"]:::api
  APIModule["Module API"]:::api
  APIBinder["Binder API\n(controlled configuration surface)"]:::api
  APIData["Data[T] API\n(type-safe key/contract)"]:::api
  APIErrors["Error Types\n(typed validation failures)"]:::error
end

subgraph "Internal Framework Core"
  direction TB

  subgraph "Assembly Engine (Orchestrator)"
    direction TB
    EngLifecycle["Lifecycle\ninstall → configure → validate → finalize"]:::core
    EngOutputs["Wiring Result\nAssembled Graph / Ready Outputs"]:::core
  end

  subgraph "Registries"
    direction TB
    ModRegistry["Module Registry\n(signature + uniqueness + singleton policy)"]:::core
    DataRegistry[("Data Registry\n(key → producer mapping)\nuniqueness + clash checks")]:::db
  end

  subgraph "Graph / Resolution Layer"
    direction TB
    GraphBuilder["Dependency Resolver / Graph Builder\n(edges: consumes → produces)"]:::core
  end

  subgraph "Validation Pipeline"
    direction TB
    ValModuleSig["Module Signature Validator\n(pkg path + module name)"]:::core
    ValSingleton["Singleton Policy Handler"]:::core
    ValDataSig["Data Key Signature Validator\n(signature + cross-package clashes)"]:::core
    ValDupProducer["Duplicate Producer Detector"]:::core
    ValMissing["Missing Producer / Unresolved Dependency Checker"]:::core
    ValCycle["Cycle Detector\n(if supported)"]:::core
  end
end

subgraph "Non-Runtime Engineering System (CI / Quality)"
  direction TB
  CIWorkflows["GitHub Actions Workflows\n(test / pre-commit / scorecard)"]:::ops
  Dependabot["Dependency Update Automation"]:::ops
  PreCommit["Pre-commit Configuration"]:::ops
  Codecov["Coverage Configuration"]:::ops
  Security["Security Policy"]:::ops
  GoModule["Go Module Packaging\n(go.mod / go.sum)"]:::ops
  Docs["User Docs\nREADME + package docs"]:::ops
end

%% =========================
%% Relationships (static architecture)
%% =========================
UApp -->|"imports & uses"| APIAssembly
UApp -->|"implements"| APIModule
UMods -->|"define"| UDataKeys

APIModule -.->|"references"| APIData
UMods -->|"configured via"| APIBinder

APIAssembly -->|"owns lifecycle"| EngLifecycle
APIAssembly -->|"invokes Configure(...)"| APIModule
APIBinder -->|"mediates declarations"| DataRegistry
APIAssembly -->|"register modules"| ModRegistry
APIAssembly -->|"build edges"| GraphBuilder
GraphBuilder -->|"reads producers/consumers"| DataRegistry

EngLifecycle -->|"validate"| ValModuleSig
EngLifecycle -->|"validate"| ValSingleton
EngLifecycle -->|"validate"| ValDataSig
EngLifecycle -->|"validate"| ValDupProducer
EngLifecycle -->|"validate"| ValMissing
EngLifecycle -->|"validate"| ValCycle

ValModuleSig -->|"uses"| ModRegistry
ValSingleton -->|"uses"| ModRegistry
ValDataSig -->|"uses"| DataRegistry
ValDupProducer -->|"uses"| DataRegistry
ValMissing -->|"uses"| DataRegistry
ValMissing -->|"uses"| GraphBuilder
ValCycle -->|"uses"| GraphBuilder

EngLifecycle -->|"finalize"| EngOutputs
EngLifecycle -->|"returns errors"| APIErrors
APIErrors -->|"reported to"| UApp
EngOutputs -->|"returned to"| UApp

%% Boundary note: modules never mutate registries directly
UMods -.->|"no direct access"| DataRegistry
UMods -.->|"no direct access"| ModRegistry

%% Docs and packaging (non-runtime links)
UApp -.->|"reads"| Docs
Docs -.->|"documents"| APIAssembly
Docs -.->|"documents"| APIModule
Docs -.->|"documents"| APIBinder
Docs -.->|"documents"| APIData
GoModule -.->|"packages"| APIAssembly

%% =========================
%% Runtime wiring flow (as a vertical mini-sequence)
%% =========================
subgraph "Runtime Wiring Flow (Configure → Validate → Finalize)"
  direction TB

  S1["1) Create Assembly"]:::step
  S2["2) Install Modules"]:::step
  S3["3) Compute Module Signatures\n& enforce uniqueness/singleton"]:::step
  S4["4) Configure Module A (Binder)"]:::step
  S5["5) Provide(Data[X]) → RegisterProducer"]:::step
  S6["6) Configure Module B (Binder)"]:::step
  S7["7) Consume(Data[X]) → Resolve/Record edge"]:::step
  S8["8) Validate registries + graph\n(dupes/clashes/missing/cycles)"]:::step
  S9["9) Finalize → Wiring Result OR Error"]:::step

  S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9
end

S1 -->|"API"| APIAssembly
S2 -->|"Install"| APIAssembly
S3 -->|"register"| ModRegistry
S4 -->|"Configure(binder)"| APIModule
S5 -->|"RegisterProducer"| DataRegistry
S6 -->|"Configure(binder)"| APIModule
S7 -->|"record dependency"| GraphBuilder
S8 -->|"emit typed errors"| APIErrors
S9 -->|"returns"| EngOutputs

%% =========================
%% Click events (component mapping)
%% =========================
click APIAssembly "https://github.com/goosz/modz/blob/main/assembly.go"
click EngLifecycle "https://github.com/goosz/modz/blob/main/assembly.go"
click EngOutputs "https://github.com/goosz/modz/blob/main/assembly.go"
click APIModule "https://github.com/goosz/modz/blob/main/module.go"
click APIBinder "https://github.com/goosz/modz/blob/main/binder.go"
click APIData "https://github.com/goosz/modz/blob/main/data.go"
click DataRegistry "https://github.com/goosz/modz/blob/main/data_registry.go"
click APIErrors "https://github.com/goosz/modz/blob/main/errors.go"
click Docs "https://github.com/goosz/modz/blob/main/README.md"
click GoModule "https://github.com/goosz/modz/blob/main/go.mod"
click CIWorkflows "https://github.com/goosz/modz/blob/main/.github/workflows/test.yaml"
click CIWorkflows "https://github.com/goosz/modz/blob/main/.github/workflows/pre-commit.yaml"
click CIWorkflows "https://github.com/goosz/modz/blob/main/.github/workflows/scorecard.yaml"
click Dependabot "https://github.com/goosz/modz/blob/main/.github/dependabot.yml"
click PreCommit "https://github.com/goosz/modz/blob/main/.pre-commit-config.yaml"
click Codecov "https://github.com/goosz/modz/blob/main/codecov.yml"
click Security "https://github.com/goosz/modz/blob/main/SECURITY.md"

click ValModuleSig "https://github.com/goosz/modz/blob/main/errors.go"
click ValDataSig "https://github.com/goosz/modz/blob/main/errors.go"
click ValDupProducer "https://github.com/goosz/modz/blob/main/errors.go"
click ValMissing "https://github.com/goosz/modz/blob/main/errors.go"
click ValCycle "https://github.com/goosz/modz/blob/main/errors.go"
click ValSingleton "https://github.com/goosz/modz/blob/main/errors.go"

click APIAssembly "https://github.com/goosz/modz/blob/main/assembly_test.go"
click APIModule "https://github.com/goosz/modz/blob/main/mock_module_test.go"
click APIBinder "https://github.com/goosz/modz/blob/main/binder_test.go"
click APIData "https://github.com/goosz/modz/blob/main/data_test.go"
click APIData "https://github.com/goosz/modz/blob/main/mock_data_test.go"
click DataRegistry "https://github.com/goosz/modz/blob/main/data_registry_test.go"
click Docs "https://github.com/goosz/modz/blob/main/doc.go"
click GoModule "https://github.com/goosz/modz/blob/main/go.sum"

%% =========================
%% Styles
%% =========================
classDef user fill:#2ecc71,stroke:#1e8449,color:#0b2e13,stroke-width:1.5px
classDef api fill:#3498db,stroke:#1f618d,color:#071a2a,stroke-width:1.5px
classDef core fill:#b3b6b7,stroke:#626567,color:#111111,stroke-width:1.2px
classDef db fill:#95a5a6,stroke:#566573,color:#111111,stroke-width:1.5px
classDef error fill:#e74c3c,stroke:#922b21,color:#ffffff,stroke-width:1.5px
classDef ops fill:#f4d03f,stroke:#b7950b,color:#2a2400,stroke-width:1.2px
classDef step fill:#af7ac5,stroke:#5b2c6f,color:#1b0f22,stroke-width:1.2px
```
