Files

MechaCat02 b8b544816d chore: initial scaffold — workspace, docs, blueprint

Sets up the PiCloud monorepo as a Cargo workspace organised around the
three-service architecture (manager / orchestrator / executor), each
backed by a *-core library crate so the same logic powers both the MVP
all-in-one `picloud` binary and the future split-process cluster mode.

  * crates/shared, executor-core, orchestrator-core, manager-core
    define the library surface and trait seams between the three
    services (`ExecutorClient`, `ScriptResolver`, `ScriptRepository`).
  * crates/picloud is the MVP entrypoint; serves /healthz on 8080
    (override via PICLOUD_BIND).
  * crates/picloud-{manager,orchestrator,executor} are skeleton
    binaries that keep the crate boundaries honest until cluster
    mode is built out in v1.3+.
  * docs/git-workflow.md defines the trunk-based workflow:
    short-lived branches, Conventional Commits, separate hotfix
    flow with mandatory reproduction tests.
  * CLAUDE.md captures the working rules for future Claude sessions.

Workspace passes `cargo fmt`, `cargo clippy -D warnings` (with
pedantic enabled), and `cargo test --workspace`. The all-in-one
binary responds on `/healthz` and `/`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-22 23:16:32 +02:00

5.0 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

PiCloud is a self-hosted, event-driven serverless compute platform. Users upload Rhai scripts, get HTTP endpoints. Optimized for solo-dev / consumer hardware (single node MVP, multi-node cluster in v1.3+).

Authoritative design: serverless_cloud_blueprint.md. The blueprint is a living document — when architecture decisions are made in conversation that contradict it, treat the latest decision as truth and update the blueprint.

Three-Service Architecture

The platform splits into three logical services, each backed by a *-core library crate so the same logic runs in single-process MVP mode and split-process cluster mode:

Service	Role	Library crate
Manager	Control plane: script CRUD, scheduling/cron, dashboard backend, config. Single-writer to Postgres.	`manager-core`
Orchestrator	Per-node ingress: receives HTTP (later SMTP, queue) events, resolves script, dispatches to local executor. Stateless.	`orchestrator-core`
Executor	Per-node compute: runs Rhai scripts in a sandboxed engine. Stateless.	`executor-core`

In MVP, all three run in one process (picloud binary). In cluster mode, each runs as its own binary on each node, with one manager total and one orchestrator + executor per node.

Key boundary: the orchestrator never imports executor-core directly — it depends on an ExecutorClient trait. The local impl calls executor-core in-process; the remote impl is an HTTP client. Same pattern keeps cluster mode a swap, not a rewrite.

Path Scheme

/api/admin/* — manager (control plane: script CRUD, config, dashboard API)
/api/execute/{id} — orchestrator (data plane: invoke a script by ID)
/exec/* — orchestrator (data plane: invoke scripts at custom paths, v1.1+)
/healthz — liveness (orchestrator)
/ and static assets — dashboard (SvelteKit static build, served by Caddy)

Caddy fronts everything. Same Caddyfile shape works for single-node and cluster — only upstream targets change.

Tech Stack

Rust 1.92+ workspace, pinned via rust-toolchain.toml
Axum for HTTP, Tokio async, sqlx for Postgres
Rhai embedded scripting (in executor-core)
PostgreSQL 15+ with pgcrypto and (v1.1+) hstore
SvelteKit dashboard, static adapter, CodeMirror 6 for the script editor
Caddy 2 reverse proxy (auto-HTTPS in prod)
Docker Compose for dev and single-node prod

Common Commands

# Rust workspace
cargo check --workspace
cargo test --workspace
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings

# Run the all-in-one binary (MVP entry point)
cargo run -p picloud

# Run a single test
cargo test -p executor-core sandbox::tests::respects_operation_budget

# Dashboard (from dashboard/)
npm run dev
npm run build
npm run check

# Full stack (once docker-compose.yml exists)
docker compose up
docker compose down -v   # reset Postgres data

Workspace Layout

crates/
  shared/                 # cross-cutting types (Script, IDs, error enum, db pool)
  executor-core/          # Rhai engine, sandbox, ctx, log, SDK
  orchestrator-core/      # event ingress + ExecutorClient trait + dispatch
  manager-core/           # control plane: repos, scheduler, config
  picloud/                # ★ MVP all-in-one binary
  picloud-manager/        # cluster mode binary (skeleton)
  picloud-orchestrator/   # cluster mode binary (skeleton)
  picloud-executor/       # cluster mode binary (skeleton)
dashboard/                # SvelteKit
caddy/                    # Caddyfile, Caddyfile.prod
docker/                   # Dockerfiles
docs/
  git-workflow.md         # trunk-based workflow
  architecture.md         # (TBD)

Working Rules

Honor the three-service boundary. Don't reach across *-core crates. If orchestrator-core needs something from manager-core, define a trait in shared and inject the impl.
executor-core has no Postgres dependency. Data-plane services (kv, docs, users — v1.1+) come in via injected ServiceProvider traits.
Database writes only from manager-core. orchestrator-core reads scripts (cached); executor-core doesn't touch the DB.
MVP builds only the picloud all-in-one binary. The three split binaries exist as skeletons so the crate boundaries stay honest; flesh them out only when cluster mode is being implemented.
Trunk-based dev. See docs/git-workflow.md. No long-lived branches. Feature flags for incomplete work.

Out of MVP

Queue triggers, cron triggers, SMTP ingress, KV / docs / email / users / HTTP SDKs in scripts, interceptors, workflows, function-to-function invoke(), auth, multi-tenancy, secrets, metrics dashboard. All deferred to v1.1+ per the blueprint. Don't pre-build for them — but don't make decisions that close the door on them either.

5.0 KiB Raw Blame History