# 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.