From 84509c19e00db61b59c5a23a0440e6f3d1b8cd55 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Sat, 10 Jan 2026 19:10:44 +0100 Subject: [PATCH] Add initial vision and project context Establishes Arbor as a Kubernetes-native git server with event-sourced metadata, designed for AI-assisted software development workflows. Key aspects: - Event sourcing for all metadata (issues, PRs, reviews) - Gitaly-style git storage for horizontal scaling - DDD bounded contexts (Repository, Collaboration, Planning, Identity) - First-class AI integration with structured issue data - Built on Aether and IRIS Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++ vision.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 278 insertions(+) create mode 100644 CLAUDE.md create mode 100644 vision.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b36bd5b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,136 @@ +# Arbor + +Kubernetes-native git server with event-sourced metadata, built for AI-assisted software development. + +## Organization Context + +This repo is part of Flowmade. See: +- [Organization manifesto](https://git.flowmade.one/flowmade-one/architecture/src/branch/main/manifesto.md) - who we are, what we believe +- [Vision](./vision.md) - what this specific product does + +## Related Projects + +- [Aether](https://git.flowmade.one/flowmade-one/aether) - Event sourcing runtime (Arbor is built on this) +- [IRIS](https://git.flowmade.one/flowmade-one/iris) - UI framework (for Arbor's web interface) +- [Architecture](https://git.flowmade.one/flowmade-one/architecture) - AI workflow commands used with Arbor + +## Setup + +```bash +git clone git@git.flowmade.one:flowmade-one/arbor.git +cd arbor +go mod download +``` + +Requires NATS server for integration tests: +```bash +brew install nats-server +nats-server -js +``` + +## Project Structure + +``` +arbor/ +├── cmd/ +│ └── arbor/ # Main binary +├── internal/ +│ ├── domain/ # DDD aggregates and events +│ │ ├── repository/ # Repository aggregate +│ │ ├── issue/ # Issue aggregate +│ │ ├── pullrequest/# PullRequest aggregate +│ │ └── ... +│ ├── git/ # Git storage service +│ ├── api/ # gRPC and HTTP APIs +│ └── projection/ # Read models +├── deploy/ +│ └── helm/ # Kubernetes deployment +└── web/ # IRIS-based UI +``` + +## Development + +```bash +make build # Build the binary +make test # Run tests +make lint # Run linters +``` + +## Architecture + +### Event Sourcing for Metadata + +All git metadata (issues, PRs, reviews, comments, milestones) is event-sourced using Aether: + +```go +// Issue aggregate +type Issue struct { + aether.AggregateBase + Title string + Description string + State IssueState + Labels []string +} + +// Commands produce events +func (i *Issue) HandleCommand(cmd aether.Command) ([]aether.Event, error) { + switch c := cmd.(type) { + case *CreateIssue: + return []aether.Event{&IssueCreated{...}}, nil + case *CloseIssue: + return []aether.Event{&IssueClosed{...}}, nil + } +} + +// Events rebuild state +func (i *Issue) ApplyEvent(evt aether.Event) { + switch e := evt.(type) { + case *IssueCreated: + i.Title = e.Title + i.State = Open + case *IssueClosed: + i.State = Closed + } +} +``` + +### Git Storage Service + +Inspired by GitLab's Gitaly - a dedicated service that owns git operations: + +- gRPC API for all git operations +- Sharded by consistent hashing on repository path +- Local SSD storage per shard (no NFS) +- Horizontal scaling via StatefulSet + +### Bounded Contexts + +| Context | Aggregates | Events | +|---------|------------|--------| +| Repository | Repository, Branch | RepositoryCreated, BranchCreated, CommitPushed | +| Collaboration | PullRequest, Review | PullRequestOpened, ReviewSubmitted, PullRequestMerged | +| Planning | Issue, Milestone, Release | IssueCreated, IssueClosed, MilestoneCompleted | +| Identity | User, Organization | UserCreated, OrganizationCreated, MemberAdded | + +### AI Integration Points + +Arbor exposes structured data for AI assistants: + +```go +// Issues have structured fields AI can parse +type Issue struct { + Title string + Description string + AcceptanceCriteria []Criterion // Testable requirements + AffectedFiles []string // Hint for where to look + Dependencies []IssueRef // What blocks this + VerticalSlice *SliceRef // Parent feature +} +``` + +## Key Patterns + +- **Events are truth** - All metadata changes are events, never direct mutations +- **Git is separate** - Git storage is a dedicated service, not part of the domain +- **DDD aggregates** - Repository, Issue, PullRequest are real aggregates with behavior +- **Kubernetes-native** - Designed for K8s from day one, not adapted after diff --git a/vision.md b/vision.md new file mode 100644 index 0000000..7562fad --- /dev/null +++ b/vision.md @@ -0,0 +1,142 @@ +# Vision + +This product vision builds on the [organization manifesto](https://git.flowmade.one/flowmade-one/architecture/src/branch/main/manifesto.md). + +## Who This Product Serves + +### Flowmade Developers + +The team building Flowmade's platform. They need a git server and product management system that integrates seamlessly with AI-assisted development workflows. Current tools (GitHub, Gitea) weren't designed for how AI changes software development. + +*Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.* + +### Teams Doing AI-Assisted Development + +Development teams using AI coding assistants who need better tooling for tracking work, managing vertical slices, and maintaining context across the development lifecycle. + +*Extends: Organizations (from manifesto) - they need tools that support their evolving workflows.* + +## What They're Trying to Achieve + +These trace back to organization-level jobs: + +| Product Job | Enables Org Job | +|-------------|-----------------| +| "Git hosting that scales horizontally without NFS bottlenecks" | "Delivering solutions faster with maintained quality" | +| "Track features, milestones, and releases in one place" | "Help me evolve my solutions as my business changes" | +| "AI assistants understand my issues and can work on them" | "Help me reduce dependency on developers" (AI handles more) | +| "Full audit trail of every change and decision" | "Adapting solutions as needs evolve" (replay, audit, understand) | +| "Vertical slices tracked from idea to deployment" | "Software aligned with actual workflows" | + +## The Problem + +Current git hosting and issue tracking tools were designed before AI-assisted development: + +- **Not AI-native.** GitHub/Gitea issues are free-form text. AI assistants must scrape and interpret. There's no structured way to express what AI needs to implement a feature. +- **Poor scaling story.** Self-hosted options (Gitea) don't scale horizontally. Git operations hit NFS bottlenecks. GitLab solved this with Gitaly, but it's complex. +- **Siloed concerns.** Git hosting, issue tracking, and CI are separate systems with brittle integrations. Context is lost between tools. +- **No audit trail.** Current state only. Why was this decision made? What changed? Lost to time. + +## The Solution + +Arbor is a Kubernetes-native git server and product management platform built for AI-assisted development: + +- **Event-sourced metadata.** Full audit trail of every change. Issues, PRs, reviews, releases - all events, all history, always. +- **Horizontal git scaling.** Gitaly-style architecture: dedicated git storage service with gRPC API, sharded by consistent hashing. +- **Structured for AI.** Issues express what AI needs: acceptance criteria, affected files, dependencies, vertical slice context. +- **Unified platform.** Git, issues, milestones, releases, CI - one system, one event stream, full context. +- **Kubernetes-native.** Helm install, horizontal scaling, KEDA-driven CI runners. + +Built on [Aether](https://git.flowmade.one/flowmade-one/aether) for event sourcing and [IRIS](https://git.flowmade.one/flowmade-one/iris) for UI. + +## Product Principles + +These extend the organization's guiding principles: + +### AI-First Design + +Every feature asks: "How does this help AI assistants do better work?" Issues have structured fields AI can parse. Events provide context AI can understand. + +*Extends: "AI amplifies individuals" (AI-Augmented Development)* + +### Events as Truth + +All metadata is event-sourced. Current state is a projection. History is always available. This directly implements "Auditability by default." + +*Extends: "Auditability by default" (Architecture Beliefs)* + +### Vertical Slices Over Horizontal Tasks + +Work is organized as user-visible value delivery, not technical tasks. Features, not "add persistence layer." + +*Extends: "Ship to learn" and "Working software over comprehensive documentation"* + +### Kubernetes-Native + +Not "runs on Kubernetes" - designed for Kubernetes. StatefulSets for git storage. KEDA for CI scaling. Helm for deployment. + +*Extends: "Resource Efficiency" - efficient on cloud infrastructure* + +### DDD for the Domain + +Repository, PullRequest, Issue, Milestone, Release - real aggregates with business rules. Not CRUD tables. + +*Extends: "Business language in code" (Architecture Beliefs)* + +## Non-Goals + +These extend the organization's non-goals: + +- **GitHub feature parity.** We build what matters for AI-assisted development, not everything GitHub has. +- **Generic project management.** This is for software development workflows, not arbitrary project tracking. +- **Self-contained CI.** CI runners are a scaling concern. We provide the queue and coordination, not the execution environment. +- **Replacing human judgment.** AI assistants work on issues, humans decide what to build. + +## Architecture + +This project follows organization architecture patterns. + +### Alignment + +| Belief | Pattern | How Arbor Implements | +|--------|---------|---------------------| +| Auditability by default | Event Sourcing | All metadata is events. Full history for every repo, issue, PR. | +| Business language in code | DDD | Repository, PullRequest, Issue are aggregates with behavior. | +| Independent evolution | Event-driven | Components communicate via events. New features subscribe. | +| Explicit over implicit | Commands and Events | CreateIssue (command) → IssueCreated (event). Intent and outcome distinct. | + +### Bounded Contexts + +| Context | Aggregates | Responsibility | +|---------|------------|----------------| +| **Repository** | Repository, Branch, Commit | Git storage, branches, commits, files | +| **Collaboration** | PullRequest, Review, Comment | PRs, reviews, discussions | +| **Planning** | Issue, Milestone, Release | Work tracking, product management | +| **Identity** | User, Organization, SSHKey | Users, orgs, permissions, keys | +| **CI** | Pipeline, Job, Artifact | Runners, jobs, logs, artifacts | + +## Milestones + +### M1: Git Operations + +Users can push, pull, clone repositories via SSH and HTTPS with horizontal scaling. + +**Success:** `git clone`, `git push`, `git pull` work against Arbor with multiple replicas. + +### M2: Issues and PRs + +Users can create issues, open PRs, and conduct reviews with full event history. + +**Success:** Create issue, open PR, merge - all with complete audit trail. + +### M3: AI Integration + +AI assistants can fetch issue context and create PRs programmatically. + +**Success:** Claude Code can `/work-issue` against an Arbor-hosted repo. + +### M4: Product Management + +Track milestones, releases, and vertical slices with dependency graphs. + +**Success:** `/vision` and `/roadmap` commands work against Arbor.