first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,32 @@
+# 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.
+