Architecture

Architecture

High-Level Architecture

                +--------------------+
                |  Core Admin UI    |
                | (HTMX + Go tmpl)  |
                +---------+----------+
                          |
                +---------v----------+
                |  Module UIs        |
                | (SvelteKit / any)  |
                +---------+----------+
                          |
                +---------v----------+
                |    API Gateway     |
                |  (REST + OpenAPI)  |
                +-------+------------+
                        |
         +--------------+--------------+
         |              |              |
 +-------v------+ +----v-----+ +------v------+
 | Event Bus    | |Scheduler | | Registry    |
 | (in-memory)  | |(contract)| |(ServiceReg) |
 +-------+------+ +----+-----+ +------+------+
         |              |              |
         +------+-------+------+------+
                |              |
     +----------v--------------------------+
     | Modules (all capabilities)         |
     | Zero domain code in core           |
     +------------------------------------+

Core Services

Event Bus

• Core provides an in-memory pub/sub bus for bootstrapping and single-node
• NATS available as a module (eventbus-nats) for distributed messaging
• Core defines only module-lifecycle and cluster-lifecycle event types
• Domain event types (download.completed, playback.started, etc.) are defined in contract repos

Service Registry

• FindByKind(kind string) for broad discovery — kind strings are conventions, not enums
• FindByCapability(cap string) for fine-grained service discovery
• Zero interface validation — compatibility checked by consumers and marketplace

Storage Orchestrator

• Abstracts all storage behind object IDs
• Capability-based provider negotiation (Streamable, Seekable, Watchable, AtomicMovable, Hardlinkable, TieredProvider)
• Multi-provider routing via policies
• Cache layer discovered via FindByCapability("cache.local")

Cluster Membership

• Provided by a cluster module implementing contracts.Cluster
• Gossip-based module (cluster-gossip) available
• Single-node deployments run without one (ModuleDeps.Cluster is nil)

Module Lifecycle

• Register -> Init -> Start -> Running -> Stopping -> Stopped
• Multi-kind registration — modules can declare multiple kind strings
• Core performs NO interface validation

Internal Communication

All internal communication goes through the event bus or gRPC mesh. Modules never call each other directly.

Design Decisions

Fabric-Only Core

Core defines only infrastructure contracts. Domain contracts live in versioned module repos (github.com/Muxcore-Media/contracts-*). Core never changes for a new media paradigm.

Event-Driven with Request/Reply

Events for state changes (types defined in contract repos). Request/reply for queries. Events are the primary integration pattern.

Capability-Based Interfaces

Small interfaces (Streamable, Seekable, Watchable) rather than monolithic ones. Modules detect capabilities at runtime.

Services via Discovery

Modules discover SecretsProvider, DatabaseProvider, CacheLayer, etc. via Registry.FindByCapability(). Nothing domain-specific is pre-wired in ModuleDeps.