first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Design
+
+## Metadata backend
+
+`PLATFORM_STORAGE_BACKEND` selects the platform metadata store:
+
+- `file`: default local durable snapshot at `PLATFORM_METADATA_PATH`.
+- `memory`: test/disposable storage.
+- `mysql`: MySQL-backed metadata snapshot using `PLATFORM_MYSQL_DSN`.
+
+The first MySQL implementation stores one platform-owned JSON snapshot in a `platform_metadata_snapshots` table. This gives operators a real durable MySQL option now while preserving the existing `repo.Store` boundary. Later changes can normalize individual repositories into relational tables without changing handlers or services.
+
+## Log body backend
+
+`PLATFORM_LOG_BODY_BACKEND` selects log body storage separately:
+
+- empty: follows the metadata backend, except `mysql` maps to `file`.
+- `file`: segmented JSONL log files in `PLATFORM_LOG_DIR`.
+- `memory`: tests/disposable local runs.
+
+MySQL metadata storage does not imply MySQL log bodies. Hundreds or thousands of servers should use segmented files for local deployments and log-optimized stores such as ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments in production.
+
+## Docker guidance
+
+The root `docker-compose.yml` keeps the default file backend. It includes commented MySQL service/config blocks so operators can uncomment them when they want local MySQL metadata:
+
+```text
+PLATFORM_STORAGE_BACKEND=mysql
+PLATFORM_MYSQL_DSN=platform:platform@tcp(mysql:3306)/platform?parseTime=true
+PLATFORM_LOG_BODY_BACKEND=file
+```
+
+## Failure behavior
+
+If `PLATFORM_STORAGE_BACKEND=mysql` is set without `PLATFORM_MYSQL_DSN`, platform startup fails with a direct configuration error. If the DSN is present but the database is unreachable, startup fails fast rather than silently falling back to memory.
+