How goosz/modz works
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)