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