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>
2026-01-10 19:10:44 +01:00
parent bff24e94db
commit 84509c19e0
2 changed files with 278 additions and 0 deletions
--- a/CLAUDE.md
+++ 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