browser/platform/README.md

platform

Backend control plane for the game server management platform.

Responsibilities

• Users, roles, permissions, sessions, and audit.
• Game management plugin installation metadata and marketplace views.
• Server instance records and lifecycle orchestration.
• AI provider configuration and platform-mediated AI invocation.
• Run registration, capabilities, jobs, artifacts, log stream metadata, and storage adapters.

Required Directory Plan

Implementation should use dedicated directories for:

• api/: route wiring and HTTP/gRPC adapters.
• dto/: request and response structures.
• domain/: business types and aggregates.
• model/: database models only.
• repo/: repository interfaces and persistence implementations.
• service/: use cases and orchestration.
• protocol/: run, plugin, artifact, log, and AI contracts.
• validator/: validation rules.
• config/: configuration structures and loading.
• shared/: small shared helpers.

Do not put DTOs, database models, or protocol structs inside handlers or service functions.

Development Baseline

Tooling:

• Go 1.25.1.
• Module: browser.local/platform.

Commands:

go test ./...
go run ./cmd/platform

Runtime configuration:

• PLATFORM_ADDR: local listen address, default :8080.
• PLATFORM_STORAGE_BACKEND: storage backend, default file; use memory only for tests or disposable local runs.
• PLATFORM_MYSQL_DSN: MySQL DSN used when PLATFORM_STORAGE_BACKEND=mysql, for example platform:platform@tcp(127.0.0.1:3306)/platform?parseTime=true.
• PLATFORM_DATA_DIR: default platform data directory, default .platform-data.
• PLATFORM_METADATA_PATH: file-backed metadata snapshot path, default .platform-data/metadata.json.
• PLATFORM_LOG_BODY_BACKEND: log body backend, default follows metadata backend except MySQL uses file; supported values are file and memory.
• PLATFORM_LOG_DIR: segmented log body directory, default .platform-data/logs.

MySQL configuration example:

export PLATFORM_STORAGE_BACKEND=mysql
export PLATFORM_MYSQL_DSN='platform:platform@tcp(127.0.0.1:3306)/platform?parseTime=true'
export PLATFORM_LOG_BODY_BACKEND=file
export PLATFORM_LOG_DIR=.platform-data/logs
go run ./cmd/platform

MySQL is the platform metadata database here. It stores the platform metadata snapshot table and should later hold normalized users/plugins/servers/jobs/audit/log stream indexes. It is not the high-volume log body store; keep log bodies in segmented files locally, or add a future ClickHouse/Loki/OpenSearch/object-storage LogBodyStore adapter for production scale.

For local direct debugging, copy platform/.env.example to platform/.env, edit the values, and run:

go run ./cmd/platform

The platform process automatically reads root .env and platform/.env before loading configuration. Explicitly exported process environment values still take precedence over values in those files.

For Docker, the root docker-compose.yml sets platform data under /data/platform and mounts it through the platform-data named volume.

Current executable behavior includes the platform API, local auth/session support, durable file-backed metadata, segmented log bodies, run control/job/log/artifact routes, plugin bridge dispatch, and platform-mediated AI invocation.