92
CLAUDE.md
Normal file
92
CLAUDE.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Forage Client - AI Development Guide
|
||||
|
||||
## Project Overview
|
||||
|
||||
Forage is the managed platform and registry for [Forest](https://src.rawpotion.io/rawpotion/forest) - an infrastructure-as-code tool that lets organisations codify their development workflows, CI, deployments, and component sharing. Forage extends forest by providing:
|
||||
|
||||
- **Component Registry**: Host and distribute forest components
|
||||
- **Managed Deployments**: Push a `forest.cue` manifest and get automatic deployment (Heroku-like experience)
|
||||
- **Container Runtimes**: Pay-as-you-go alternative to Kubernetes
|
||||
- **Managed Services**: Databases, user management, observability, and more
|
||||
- **Organisation Management**: Teams, billing, access control
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Language**: Rust
|
||||
- **Web Framework**: Axum
|
||||
- **Templating**: MiniJinja (server-side rendered)
|
||||
- **Styling**: Tailwind CSS (via standalone CLI)
|
||||
- **Database**: PostgreSQL (via SQLx, compile-time checked queries)
|
||||
- **Build System**: Forest + Mise for task running
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
/
|
||||
├── CLAUDE.md # This file
|
||||
├── Cargo.toml # Workspace root
|
||||
├── forest.cue # Forest project manifest
|
||||
├── mise.toml # Task runner configuration
|
||||
├── crates/
|
||||
│ ├── forage-server/ # Main axum web server
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── main.rs
|
||||
│ │ │ ├── routes/ # Axum route handlers
|
||||
│ │ │ ├── templates/ # MiniJinja templates
|
||||
│ │ │ └── state.rs # Application state
|
||||
│ │ └── Cargo.toml
|
||||
│ ├── forage-core/ # Business logic, pure functions
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── lib.rs
|
||||
│ │ │ ├── registry/ # Component registry logic
|
||||
│ │ │ ├── deployments/ # Deployment orchestration
|
||||
│ │ │ └── billing/ # Pricing and billing
|
||||
│ │ └── Cargo.toml
|
||||
│ └── forage-db/ # Database layer
|
||||
│ ├── src/
|
||||
│ │ ├── lib.rs
|
||||
│ │ └── migrations/
|
||||
│ └── Cargo.toml
|
||||
├── templates/ # Shared MiniJinja templates
|
||||
│ ├── base.html.jinja
|
||||
│ ├── pages/
|
||||
│ └── components/
|
||||
├── static/ # Static assets (CSS, JS, images)
|
||||
├── specs/ # VSDD specification documents
|
||||
└── tests/ # Integration tests
|
||||
```
|
||||
|
||||
## Development Methodology: VSDD
|
||||
|
||||
This project follows **Verified Spec-Driven Development (VSDD)**. See `specs/VSDD.md` for the full methodology.
|
||||
|
||||
### Key Rules for AI Development
|
||||
|
||||
Follow the VSDD pipeline **religiously**. No shortcuts, no skipping phases.
|
||||
|
||||
1. **Spec First**: Never implement without a spec in `specs/`. Read the spec before writing code.
|
||||
2. **Test First**: Write failing tests before implementation. No code exists without a test that demanded it. Confirm tests fail (Red) before writing implementation (Green).
|
||||
3. **Pure Core / Effectful Shell**: `forage-core` is the pure, testable core. `forage-server` is the effectful shell. Database access lives in `forage-db`.
|
||||
4. **Minimal Implementation**: Write the minimum code to pass each test. Refactor only after green.
|
||||
5. **Trace Everything**: Every spec requirement maps to tests which map to implementation.
|
||||
6. **Adversarial Review**: After implementation, conduct a thorough adversarial review (Phase 3). Save reviews in `specs/reviews/`.
|
||||
7. **Feedback Loop**: Review findings feed back into specs and tests (Phase 4). Iterate until convergence.
|
||||
8. **Hardening**: Run clippy, cargo-audit, and static analysis (Phase 5). Property-based tests where applicable.
|
||||
|
||||
## Commands
|
||||
|
||||
- `mise run develop` - Start the dev server
|
||||
- `mise run test` - Run all tests
|
||||
- `mise run db:migrate` - Run database migrations
|
||||
- `mise run build` - Build release binary
|
||||
- `forest run <command>` - Run forest-defined commands
|
||||
|
||||
## Conventions
|
||||
|
||||
- Use `snake_case` for all Rust identifiers
|
||||
- Prefer `thiserror` for error types in libraries, `anyhow` in binaries
|
||||
- All database queries use SQLx compile-time checking
|
||||
- Templates use MiniJinja with `.html.jinja` extension
|
||||
- Routes are organized by feature in `routes/` modules
|
||||
- All public API endpoints return proper HTTP status codes
|
||||
- Configuration via environment variables with sensible defaults
|
||||
Reference in New Issue
Block a user