From 51916621eace7678bb5d42ca0283eb3a3de33a17 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Sat, 10 Jan 2026 15:14:37 +0100 Subject: [PATCH] Update vision to align with manifesto inheritance model Restructure vision.md to properly extend the organization manifesto: - Add personas that extend org personas (Flowmade Developers, Go Teams) - Add jobs table tracing product jobs to org jobs - Add product principles extending org principles - Connect event sourcing to manifesto's "comprehensive activity records" belief - Add resource consciousness alignment (ARM64, modest hardware) - Expand non-goals with explicit manifesto references - Add architecture section showing pattern alignment Co-Authored-By: Claude Opus 4.5 --- vision.md | 104 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 85 insertions(+), 19 deletions(-) diff --git a/vision.md b/vision.md index 3db2ced..086b967 100644 --- a/vision.md +++ b/vision.md @@ -1,14 +1,43 @@ -# Aether Vision +# Vision -Distributed actor system with event sourcing for Go, powered by NATS. +This product vision builds on the [organization manifesto](https://git.flowmade.one/flowmade-one/architecture/src/branch/main/manifesto.md). -## Organization Context +## Who This Product Serves -This repo is part of Flowmade. See [organization manifesto](https://git.flowmade.one/flowmade-one/architecture/src/branch/main/manifesto.md) for who we are and what we believe. +### Flowmade Developers -## What This Is +The team building Flowmade's platform. They need reliable, auditable infrastructure for distributed systems without reinventing clustering and event sourcing. -Aether is an open-source infrastructure library for building distributed, event-sourced systems in Go. It provides: +*Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.* + +### Go Teams Building Event-Sourced Systems + +Teams implementing event sourcing and CQRS patterns who want clear primitives that compose well, not a heavyweight framework. + +*Extends: Organizations (from manifesto) - they need maintainable, evolvable infrastructure.* + +## What They're Trying to Achieve + +These trace back to organization-level jobs: + +| Product Job | Enables Org Job | +|-------------|-----------------| +| "Build distributed systems without reinventing clustering" | "Delivering solutions faster with maintained quality" | +| "Store events as source of truth with full history" | "Adapting solutions as needs evolve" (replay, rebuild, audit) | +| "Scale horizontally without complexity" | "Reducing developer dependency" (infrastructure handles it) | +| "Isolate concerns with namespaces" | "Software aligned with actual workflows" (logical boundaries) | + +## The Problem + +Building distributed, event-sourced systems in Go requires assembling many pieces: event storage, pub/sub, clustering, leader election. Existing solutions are either: + +- **Too heavy** - Full frameworks with opinions about your domain +- **Too light** - Just pub/sub, you build everything else +- **Not NATS-native** - Bolted-on integrations that don't leverage JetStream properly + +## The Solution + +Aether provides clear primitives that compose well: - **Event sourcing primitives** - Event, EventStore interface, snapshots - **Event stores** - In-memory (testing) and JetStream (production) @@ -16,22 +45,59 @@ Aether is an open-source infrastructure library for building distributed, event- - **Cluster management** - Node discovery, leader election, shard distribution - **Namespace isolation** - Logical boundaries for multi-scope deployments -## Who This Serves +Built for JetStream from the ground up, not bolted on. -- **Go developers** building distributed systems -- **Teams** implementing event sourcing and CQRS patterns -- **Projects** needing actor-based concurrency with event persistence +## Product Principles -## Goals +These extend the organization's guiding principles: -1. **Simple event sourcing** - Clear primitives that compose well -2. **NATS-native** - Built for JetStream, not bolted on -3. **Horizontal scaling** - Consistent hashing, shard migration, leader election -4. **Namespace isolation** - Logical boundaries without infrastructure overhead +### Primitives Over Frameworks + +Provide composable building blocks, not an opinionated framework. Let users build what they need. + +*Extends: "Design amplification for individual capability"* + +### NATS-Native + +Built for JetStream from the start. Leverage NATS capabilities fully rather than abstracting them away. + +*Extends: "Sensible defaults with available alternatives"* + +### Resource Conscious + +Efficient on modest hardware. NATS is lightweight; Aether should be too. ARM64 friendly. + +*Extends: "Software performs adequately on standard-capability hardware" and "ARM64 optimization"* + +### Events as Complete History + +Events are the source of truth. State is derived. This directly implements the manifesto belief that "systems should maintain comprehensive activity records, not merely current snapshots." + +*Extends: "Systematize information rather than merely documenting it"* ## Non-Goals -- Opinionated multi-tenancy (product layer concern) -- Domain-specific abstractions (use the primitives) -- GraphQL/REST API generation (build on top) -- UI components (see iris) +These extend the organization's non-goals: + +- **Opinionated multi-tenancy.** Product layer concern - Aether provides namespace primitives, not tenant management. +- **Domain-specific abstractions.** Use the primitives to build your domain model. +- **GraphQL/REST API generation.** Build on top of Aether, not inside it. +- **UI components.** See iris for UI concerns. +- **Replacing human judgment.** Aether automates infrastructure, not decisions. + +## Architecture + +This project follows organization architecture patterns. + +### Alignment + +- **Event Sourcing**: Core to this library - events as source of truth +- **Auditability**: Full event history, immutable records, replayable state +- **Loose Coupling**: Event bus for communication, namespaces for isolation +- **Domain Language**: Event types reflect business concepts + +### Intentional Divergences + +| Area | Standard Pattern | What We Do Instead | Why | +|------|------------------|-------------------|-----| +| Domain modeling | DDD aggregates | Generic Actor abstraction | Library provides primitives, not domain opinions |