flowmade-one/arbor
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add initial vision and project context

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-10 19:10:44 +01:00
parent bff24e94db
commit 84509c19e0
2 changed files with 278 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
CLAUDE.md Normal file
View File

@@ -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

142
vision.md Normal file
View File

@@ -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.