Skip to main content

Domain: platform

Curated entry point for the engineer-facing capabilities every business domain consumes — shared TypeScript packages, the on-call agent, alert / SLO / runbook content, CI scripts, dev tooling. Cross-functional: owned across the whole engineering org rather than by any one business team.

See the sibling infra/ domain for the underlying substrate (Terraform, Helm, K8s admin, Kafka/Vault/Aurora/Redis cluster admin, GitLab self-hosted server administration) that platform itself runs on top of.

Owner​

Founder + agents (Phase 1). Future-team-shape: a small platform engineering function once the company grows beyond 3-4 engineers; that team consumes the substrate the infra domain owns.

Mission​

Owns the engineer-facing developer-experience layer that every business domain depends on:

  • shared TypeScript packages — @astrix/observability, @astrix/config, @astrix/db, @astrix/clients/*, @astrix/types;
  • on-call automation — the L1 enriched-paging agent and L2 read-only diagnostic agent (docs/PRD/17-engineering-standards.md Section 17.6);
  • observability content — alert rule definitions, SLO definitions, dashboard JSON, runbook prose, postmortem templates;
  • CI scripts and pre-commit / commit-msg hooks (scripts/check-*.ts, scripts/audit-*.ts);
  • documentation portal (Docusaurus) configuration, frontmatter schema, and rendering;
  • shared dev tooling — TypeScript / ESLint / Prettier / Vitest / Playwright base configs.

Boundary: platform owns capabilities engineers consume. Platform does not own the underlying substrate (the EKS cluster, Aurora cluster, Kafka cluster, Vault server, GitLab self-hosted instance, K8s control plane, DNS records, certificates) — that belongs to the infra domain. If you find yourself writing Terraform, Helm chart values for a substrate service, or running a kubectl against a cluster API, you are in infra.

Code paths​

  • Shared TypeScript packages: packages/observability/, packages/config/, packages/db/, packages/clients/vault/, packages/clients/<vendor>/, packages/types/
  • On-call agent code: apps/oncall-agent-l1/, apps/oncall-agent-l2/ (Phase 1b)
  • Alert / SLO / runbook content: infra/observability/prometheus/rules/<domain>.rules.yaml, infra/observability/slos/<slo>.slo.yaml, docs/runbooks/<id>.md, docs/postmortems/
  • CI scripts: scripts/check-*.ts, scripts/audit-*.ts, scripts/create-issue.ts
  • Dev tooling: tsconfig.base.json, .eslintrc.cjs, root prettier.config.cjs, vitest.workspace.ts, base Playwright config
  • Database schemas owned by platform itself: platform (FeatureFlag, FeatureFlagAssignment, PlatformHealthCheck)

PRD chapters that touch this domain​

TDD chapters​

(Empty — will populate. Expected: @astrix/observability package TDD, on-call-agent (L1 + L2) TDD, Docusaurus portal TDD, alert/SLO content packaging TDD.)

ADRs that affected this domain​

(All future platform-capability ADRs will land here.)

Service interfaces this domain exposes​

Platform exposes capabilities, not service interfaces in the application sense. The "interface" is the contract embedded in the shared packages:

  • @astrix/observability — structured logger (Pino), metrics emitter (prom-client), tracing wrapper (@opentelemetry/sdk-node), correlation-id propagation
  • @astrix/config — env-var validation via Zod, shared constants
  • @astrix/db — Prisma client + migration runner, schema-per-domain enforcement helpers
  • @astrix/clients/vault — typed Vault client wrapping the secrets / Transit / PKI engines
  • @astrix/types — branded primitives (AccountId, UserId, Money, BreachId)

Every service consumes these. Breaking changes to a shared package require an ADR and a coordinated rollout plan.

Events​

Platform itself does not produce or consume domain events. It owns the Kafka topic registry (packages/contracts/events/) and the schema-evolution policy that all domain events follow.

External integrations​

Platform talks to internal substrate, not external vendors. The substrate (AWS APIs, K8s API, Vault HTTP API, Strimzi CRDs, GitLab API) is owned by infra. Platform consumes those substrates through:

  • typed clients in packages/clients/* (one per substrate)
  • @astrix/observability / @astrix/config / @astrix/db package APIs (the seams that hide substrate URLs / connection strings / credentials)

If you are adding a new substrate dependency (a new SaaS, a new internal cluster, etc.), the substrate provisioning is infra; the typed client and configuration plumbing is platform.

Runbooks for this domain​

(More will land as Phase 1b alert content ships.)

On-call​

Platform owns the on-call agent code itself (L1 + L2). Page paths for platform alerts (e.g. apps/api error rate, deploy duration anomalies, observability-content drift) follow the routing matrix in Section 17.6.1. Substrate alerts (Aurora capacity, Kafka broker, Vault sealed, K8s control-plane health) page the infra rotation, not platform.

Cross-domain dependencies​

  • This domain calls: nothing in the business layer; consumes only the substrate provided by infra.
  • Every business domain depends on this layer's shared packages, alert content, and CI scripts.