bitforge/orchard
3
0
Fork 0
Code Projects Wiki Activity

Rename terminology to industry standard terms

Browse Source 
- Grove → Project
- Tree → Package
- Fruit → Artifact
- Graft → Tag
- Cultivate → Upload
- Harvest → Download

Updated across:
- Backend models, schemas, and routes
- Frontend types, API client, and components
- README documentation
- API endpoints now use /project/:project/packages pattern
This commit is contained in:
Mondo Diaz
2025-12-08 10:38:44 -06:00
parent 386ea0df4d
commit ff7df9eb3f
12 changed files with 470 additions and 485 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
README.md
View File

@@ -2,7 +2,7 @@
**Content-Addressable Storage System**
Orchard is a centralized binary artifact storage system that provides content-addressable storage with automatic deduplication, flexible access control, and multi-format package support. Like an orchard that cultivates and distributes fruit, Orchard nurtures and distributes the products of software builds.
Orchard is a centralized binary artifact storage system that provides content-addressable storage with automatic deduplication, flexible access control, and multi-format package support.
## Tech Stack
@@ -17,11 +17,11 @@ Orchard is a centralized binary artifact storage system that provides content-ad
### Currently Implemented
- **Content-Addressable Storage** - Artifacts are stored and referenced by their SHA256 hash, ensuring deduplication and data integrity
- **Grove/Tree/Fruit Hierarchy** - Organized storage structure:
- **Grove** - Top-level project container
- **Tree** - Named package within a grove
- **Fruit** - Specific artifact instance identified by SHA256
- **Grafts (Tags/Versions)** - Alias system for referencing artifacts by human-readable names (e.g., `v1.0.0`, `latest`, `stable`)
- **Project/Package/Artifact Hierarchy** - Organized storage structure:
- **Project** - Top-level organizational container
- **Package** - Named collection within a project
- **Artifact** - Specific content instance identified by SHA256
- **Tags** - Alias system for referencing artifacts by human-readable names (e.g., `v1.0.0`, `latest`, `stable`)
- **S3-Compatible Backend** - Uses MinIO (or any S3-compatible storage) for artifact storage
- **PostgreSQL Metadata** - Relational database for metadata, access control, and audit trails
- **REST API** - Full HTTP API for all operations
@@ -35,17 +35,17 @@ Orchard is a centralized binary artifact storage system that provides content-ad
|--------|----------|-------------|
| `GET` | `/` | Web UI |
| `GET` | `/health` | Health check |
| `GET` | `/api/v1/groves` | List all groves |
| `POST` | `/api/v1/groves` | Create a new grove |
| `GET` | `/api/v1/groves/:grove` | Get grove details |
| `GET` | `/api/v1/grove/:grove/trees` | List trees in a grove |
| `POST` | `/api/v1/grove/:grove/trees` | Create a new tree |
| `POST` | `/api/v1/grove/:grove/:tree/cultivate` | Upload an artifact |
| `GET` | `/api/v1/grove/:grove/:tree/+/:ref` | Download an artifact |
| `GET` | `/api/v1/grove/:grove/:tree/grafts` | List all tags/versions |
| `POST` | `/api/v1/grove/:grove/:tree/graft` | Create a tag |
| `GET` | `/api/v1/grove/:grove/:tree/consumers` | List consumers of a tree |
| `GET` | `/api/v1/fruit/:id` | Get fruit metadata by hash |
| `GET` | `/api/v1/projects` | List all projects |
| `POST` | `/api/v1/projects` | Create a new project |
| `GET` | `/api/v1/projects/:project` | Get project details |
| `GET` | `/api/v1/project/:project/packages` | List packages in a project |
| `POST` | `/api/v1/project/:project/packages` | Create a new package |
| `POST` | `/api/v1/project/:project/:package/upload` | Upload an artifact |
| `GET` | `/api/v1/project/:project/:package/+/:ref` | Download an artifact |
| `GET` | `/api/v1/project/:project/:package/tags` | List all tags |
| `POST` | `/api/v1/project/:project/:package/tags` | Create a tag |
| `GET` | `/api/v1/project/:project/:package/consumers` | List consumers of a package |
| `GET` | `/api/v1/artifact/:id` | Get artifact metadata by hash |
### Reference Formats
@@ -55,7 +55,7 @@ When downloading artifacts, the `:ref` parameter supports multiple formats:
- `v1.0.0` - Version tag
- `tag:stable` - Explicit tag reference
- `version:2024.1` - Version reference
- `fruit:a3f5d8e12b4c6789...` - Direct SHA256 hash reference
- `artifact:a3f5d8e12b4c6789...` - Direct SHA256 hash reference
## Quick Start
@@ -115,26 +115,26 @@ The frontend dev server proxies API requests to `localhost:8080`.
## Usage Examples
### Create a Grove
### Create a Project
```bash
curl -X POST http://localhost:8080/api/v1/groves \
curl -X POST http://localhost:8080/api/v1/projects \
-H "Content-Type: application/json" \
-d '{"name": "my-project", "description": "My project artifacts", "is_public": true}'
```
### Create a Tree
### Create a Package
```bash
curl -X POST http://localhost:8080/api/v1/grove/my-project/trees \
curl -X POST http://localhost:8080/api/v1/project/my-project/packages \
-H "Content-Type: application/json" \
-d '{"name": "releases", "description": "Release builds"}'
```
### Upload an Artifact (Cultivate)
### Upload an Artifact
```bash
curl -X POST http://localhost:8080/api/v1/grove/my-project/releases/cultivate \
curl -X POST http://localhost:8080/api/v1/project/my-project/releases/upload \
-F "file=@./build/app-v1.0.0.tar.gz" \
-F "tag=v1.0.0"
```
@@ -142,39 +142,39 @@ curl -X POST http://localhost:8080/api/v1/grove/my-project/releases/cultivate \
Response:
```json
{
"fruit_id": "a3f5d8e12b4c67890abcdef1234567890abcdef1234567890abcdef12345678",
"artifact_id": "a3f5d8e12b4c67890abcdef1234567890abcdef1234567890abcdef12345678",
"size": 1048576,
"grove": "my-project",
"tree": "releases",
"project": "my-project",
"package": "releases",
"tag": "v1.0.0"
}
```
### Download an Artifact (Harvest)
### Download an Artifact
```bash
# By tag
curl -O http://localhost:8080/api/v1/grove/my-project/releases/+/v1.0.0
curl -O http://localhost:8080/api/v1/project/my-project/releases/+/v1.0.0
# By fruit ID
curl -O http://localhost:8080/api/v1/grove/my-project/releases/+/fruit:a3f5d8e12b4c6789...
# By artifact ID
curl -O http://localhost:8080/api/v1/project/my-project/releases/+/artifact:a3f5d8e12b4c6789...
# Using the spec-compliant URL pattern
curl -O http://localhost:8080/grove/my-project/releases/+/latest
# Using the short URL pattern
curl -O http://localhost:8080/project/my-project/releases/+/latest
```
### Create a Tag (Graft)
### Create a Tag
```bash
curl -X POST http://localhost:8080/api/v1/grove/my-project/releases/graft \
curl -X POST http://localhost:8080/api/v1/project/my-project/releases/tags \
-H "Content-Type: application/json" \
-d '{"name": "stable", "fruit_id": "a3f5d8e12b4c6789..."}'
-d '{"name": "stable", "artifact_id": "a3f5d8e12b4c6789..."}'
```
### Search by Fruit ID
### Get Artifact by ID
```bash
curl http://localhost:8080/api/v1/fruit/a3f5d8e12b4c67890abcdef1234567890abcdef1234567890abcdef12345678
curl http://localhost:8080/api/v1/artifact/a3f5d8e12b4c67890abcdef1234567890abcdef1234567890abcdef12345678
```
## Project Structure
@@ -206,8 +206,6 @@ orchard/
│ └── vite.config.ts
├── helm/
│ └── orchard/ # Helm chart
├── migrations/
│ └── 001_initial.sql # Database schema
├── Dockerfile # Multi-stage build (Node + Python)
├── docker-compose.yml # Local development stack
└── .gitlab-ci.yml # CI/CD pipeline
@@ -257,39 +255,26 @@ See `helm/orchard/values.yaml` for all configuration options.
### Core Tables
- **groves** - Top-level project containers
- **trees** - Packages within groves
- **fruits** - Content-addressable artifacts (SHA256)
- **grafts** - Tags/aliases pointing to fruits
- **graft_history** - Audit trail for tag changes
- **harvests** - Upload event records
- **projects** - Top-level organizational containers
- **packages** - Collections within projects
- **artifacts** - Content-addressable artifacts (SHA256)
- **tags** - Aliases pointing to artifacts
- **tag_history** - Audit trail for tag changes
- **uploads** - Upload event records
- **consumers** - Dependency tracking
- **access_permissions** - Grove-level access control
- **access_permissions** - Project-level access control
- **api_keys** - Programmatic access tokens
- **audit_logs** - Immutable operation logs
## Terminology
| Orchard Term | Traditional Term | Description |
|--------------|------------------|-------------|
| Grove | Project | Top-level organizational unit |
| Tree | Package | Named collection of related artifacts |
| Fruit | Instance | Specific content identified by SHA256 |
| Seed | Dependency | Required package specification |
| Harvest | Download/Fetch | Retrieve dependencies |
| Cultivate | Upload/Publish | Store new artifact |
| Graft | Alias/Tag | Alternative name for content |
| Prune | Clean/GC | Remove unused local cache |
## Future Work
The following features from the specification are planned but not yet implemented:
The following features are planned but not yet implemented:
- [ ] CLI tool (`orchard` command)
- [ ] `orchard.ensure` file parsing
- [ ] Lock file generation (`orchard.lock`)
- [ ] Dependency file parsing
- [ ] Lock file generation
- [ ] Export/Import for air-gapped systems
- [ ] Consumer notification (pollination)
- [ ] Consumer notification
- [ ] Automated update propagation
- [ ] OIDC/SAML authentication
- [ ] API key management