# Design

## Deployment shape

The local Docker deployment runs three services:

- `platform`: Go backend listening on `:8080`, using file-backed storage under `/data/platform`.
- `run`: Go worker in `worker` mode, connecting to `http://platform:8080`, using `/data/run/workspace` and `/data/run/spool`.
- `platform_web`: static Vite build served by Nginx, proxying `/api/v1` and `/healthz` to `platform:8080`.

This matches the current architecture without introducing a new database adapter. The platform metadata and segmented log bodies are persisted in a Docker named volume. The worker has its own named volume for local workspace and spool data.

## Local debugging

Direct local execution remains environment-variable based:

- Root `.env.example` documents the common three-process setup.
- `platform/.env.example` documents backend storage knobs.
- `run/.env.example` documents worker identity, platform URL, workspace, and scheduling knobs.
- `platform_web/.env.example` documents Vite browser API and dev proxy knobs.

Developers can copy the example files to `.env` or source/export the variables before running `go run` / `npm run dev`. The project intentionally keeps Go config loading simple and does not require a checked-in secret-bearing config file.

## Storage guidance

The Docker compose default uses the durable file backend because it works without external services:

- `PLATFORM_METADATA_PATH=/data/platform/metadata.json`
- `PLATFORM_LOG_DIR=/data/platform/logs`

For larger production deployments, MySQL/Postgres should be introduced as a metadata repository adapter in a future OpenSpec change. High-volume log bodies should use a log-optimized backend such as ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments behind `LogBodyStore`; Docker compose does not pretend that MySQL is an adequate row-per-log-line body store.