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 <noreply@anthropic.com>
This commit is contained in:
136
CLAUDE.md
Normal file
136
CLAUDE.md
Normal 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
142
vision.md
Normal 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.
|
||||
Reference in New Issue
Block a user