Development conventions

Language and style

Documentation and stable identifiers are English-first; UI strings are localizable from the start.
Use idiomatic current stable Go, explicit errors and small interfaces at consumer boundaries.
Prefer server-rendered html/template views, progressive enhancement and small focused browser modules; do not introduce a large SPA framework without an accepted architectural reason.
Format and lint frontend and Go code with repository-pinned tools.
Avoid hidden global state. Inject clock, ID generator and external interfaces for deterministic tests.
Use UTC internally and IANA timezones at scheduling boundaries.

Repository shape

The implementation may refine this layout while preserving boundaries:

cmd/dogama/
cmd/dogama-agent/
internal/                non-public Go packages
web/                     embedded UI source
migrations/              append-only SQLite migrations
specs/                   schemas and normalized contracts
catalog/                 reference templates
modules/                 reference modules and fixtures
docs/
tests/integration/

Contract changes

Template schema, manifest schema, normalized module API and agent deployment plan are versioned contracts.

Backward-compatible additions do not change existing meanings.
Breaking changes require a new schema/API major version and documented migration.
Released examples are updated or retained as compatibility fixtures.
Instances pin immutable versions; runtime behavior never depends on a mutable catalog file.

Testing pyramid

Unit: domain policies, permission evaluation, cron/timezones, state transitions, retention and redaction.
Property/fuzz: paths, archive entries, schema inputs, agent plans and normalized module payloads.
Integration: SQLite migrations, disposable Docker agent, real archive workflows and WASM sandbox limits.
End-to-end: bootstrap, Palworld dry/test fixture deployment, role views, backup/restore and update rollback.

Tests must include denial and interrupted-operation cases, not only happy paths. External game APIs use recorded or purpose-built fixtures in normal CI; live Palworld verification is a separate documented test.

Migrations and compatibility

Never rewrite a released migration. Migration execution is transactional where SQLite permits and creates a pre-migration database backup for release upgrades. Store application/schema version and test upgrade from the previous release.

Dependencies and supply chain

Prefer standard-library or mature focused dependencies. Pin build tooling, review transitive changes and generate an SBOM/reproducible checksums for releases. Do not dynamically download executable code at runtime except administrator-installed validated WASM packages.

Observability

Structured technical logs use stable event names and redaction. Metrics are operationally small. Correlation/operation IDs connect HTTP, job and agent errors without storing request secrets.

Review checklist

Correct trust boundary and backend authorization?
Can input influence a host path, Docker plan, URL or secret?
Are retries/idempotency and restart recovery defined?
Could failure delete or corrupt player data?
Do documentation, schema and examples agree?
Are UI capability checks backed by server checks?
Are audit and notifications appropriately minimal?

3.3 KiB Raw Blame History