# PiCloud

A lightweight, self-hosted, event-driven serverless compute platform. Upload a [Rhai](https://rhai.rs/) script, get an HTTP endpoint. Designed to run on a single modest server with no idle CPU cost, and to scale out to a small cluster when you need it.

> **Status:** Phase 1 — MVP scaffolding in progress.
>
> The authoritative design lives in [`serverless_cloud_blueprint.md`](serverless_cloud_blueprint.md).

## Why

Existing serverless platforms are either cloud-locked, heavyweight, or both. PiCloud aims for the opposite end of the spectrum: one binary, one database, one reverse proxy — running on hardware you already own.

## Architecture (one paragraph)

PiCloud splits into three logical services — **manager** (control plane: scripts, schedules, dashboard), **orchestrator** (per-node event ingress and dispatch), and **executor** (per-node Rhai sandbox) — each backed by a `*-core` Rust library. In MVP they run in a single process; in cluster mode they run as three binaries with one manager and one orchestrator + executor per node. [Caddy](https://caddyserver.com/) fronts everything; [PostgreSQL](https://www.postgresql.org/) is the single source of truth.

See [`CLAUDE.md`](CLAUDE.md) for working notes and [`serverless_cloud_blueprint.md`](serverless_cloud_blueprint.md) for the full design.

## Quick Start

> _Coming as scaffolding lands. For now:_

```sh
# Rust toolchain (pinned via rust-toolchain.toml)
cargo check --workspace

# Run the all-in-one MVP binary (once main.rs is wired up)
cargo run -p picloud
```

## Repository Layout

```
crates/
  shared/                 cross-cutting types
  executor-core/          Rhai engine + sandbox
  orchestrator-core/      event ingress, dispatch
  manager-core/           control plane
  picloud/                MVP all-in-one binary
  picloud-{manager,orchestrator,executor}/   cluster-mode binaries (skeleton)
dashboard/                SvelteKit
caddy/                    Caddyfile
docker/                   Dockerfiles
docs/
  git-workflow.md         Trunk-based workflow
```

## Contributing

See [`docs/git-workflow.md`](docs/git-workflow.md) for the branching and commit conventions. TL;DR: trunk-based, short-lived branches, Conventional Commits, no force-pushing `main`.

## License

TBD.