Platform Orientation

Status: This page describes the established Wavemap platform as of August 5, 2026. It is the recommended first operations reading. Exact live identifiers belong in reviewed plans, provider readback, and private receipts rather than this public conceptual guide.

Wavemap is optimized for feature development without making deployment or infrastructure authority implicit. Source, artifacts, infrastructure, execution, and evidence therefore remain separate layers even though they validate one another.

The Platform In One Sentence

Git and CI identify an exact candidate; product-owned Pulumi defines the Wavemap workload in AWS while Tendril protects its state; a human selects one bounded deployment or infrastructure operation; and smoke checks plus sanitized receipts prove the result.

The Five Layers

Layer	Question It Answers	Primary Implementation
Source and policy	What change is being proposed?	Git, exact-SHA CI, path classification, TypeScript contracts, tests.
Artifact and contract	What exact bytes or facts may be delivered?	Immutable ECR images, deployment contracts, runtime parameters, release receipts, reviewed Pulumi saved plans.
Stable infrastructure	What environment exists?	Product-owned Pulumi source, AWS workload resources, and the Tendril-owned state foundation.
Bounded execution	What one operation is authorized now?	Manual GitHub workflows, protected environments, narrow OIDC roles, guarded CLI and shell entry points.
Evidence and recovery	What happened, and what could recover it?	Workflow summaries, smoke results, versioned receipts, Pulumi history/checkpoints, retained recovery evidence.

These layers overlap in validation, not authority. A Pulumi role can exist without authorizing a deployment. A commit can pass CI without being selected for Development. A deployment contract can describe the runtime without granting access to Pulumi state or database mutation.

Environment And Data Model

Environment	Purpose	Data Posture	Current Delivery Boundary
Local development	Fast application and feature iteration on a developer machine.	Docker-backed PostgreSQL, emulators, fixtures, resets, and local media are disposable.	Local commands only; local proof is not cloud-delivery evidence.
Development	Shared cloud integration, smoke, demonstrations, and release proof.	Containerized PostgreSQL and Development media remain disposable by policy, even when they persist across host stops.	Human-selected application-only delivery or the separate reviewed operator workflow.
Incubation	Not a Wavemap environment.	None. Waveguide’s Incubation model must not be inferred for Wavemap.	None.
Staging/Production	Not established.	No durability, availability, backup, recovery-objective, or compliance promise exists yet.	Requires a new environment and durability review before implementation.

Development intentionally has no routine database-affecting CD. The application-only workflow cannot migrate, seed, or reset its database. Database status, migration, and destructive reset remain human-selected operator procedures because the database is disposable but still shared with other feature and demonstration work.

Before irreplaceable corpus or uploaded media becomes valuable in Development, stop and establish a separately reviewed durability program. That program must define backup ownership, recovery proof, media/database consistency, retention, and the gate for moving data into a durable environment. Existing Development persistence is convenience, not that program.

Tendril And Product Ownership

Tendril Systems Infrastructure owns the organization-level Pulumi state foundation. Wavemap owns the application stack whose encrypted state is stored there.

Tendril Systems Infrastructure
  -> protected state backend and shared backend controls
     -> /foundation  Tendril foundation state
     -> /wavemap     Wavemap product state
     -> /waveguide   Waveguide product state

Wavemap repository
  -> Wavemap Pulumi program and guarded launcher
  -> Wavemap workload AWS resources and IAM
  -> deployment contracts, runtime configuration, workflows, and recovery procedures

The paths are separate state namespaces, not permission for one product to own or inspect the other’s resources. The Tendril repository does not own Wavemap compute, databases, registries, DNS, runtime secrets, deployment contracts, or application workflows. Conversely, Wavemap does not own the shared backend bucket or its organization-level protection controls.

Wavemap’s former workload-account backend is retained as protected recovery evidence. It is not the active authority and must not be presented as a pending migration target. Current infrastructure work uses the guarded Wavemap launcher, which fixes the Tendril /wavemap backend, the Wavemap project and stack, both AWS account identities, the passphrase file, the exact source revision, and the reviewed saved plan.

There is no separate higher-level Tendril documentation site. Both product docs therefore explain the shared foundation with the same vocabulary and then continue into their product-specific environments and controls.

How A Change Reaches Development

exact commit + successful merged-state CI
                  |
                  v
         human selects the operation
                  |
                  +-- application-only
                  |     -> exact source admission
                  |     -> database-change classification
                  |     -> immutable image digests
                  |     -> runtime deploy + endpoint/browser smoke
                  |     -> sanitized release receipt or bounded rollback
                  |
                  +-- database-affecting or destructive
                  |     -> reviewed operator recipe
                  |     -> explicit migration/reset authority
                  |
                  +-- infrastructure
                        -> guarded full-stack preview
                        -> reviewed saved-plan/source digests
                        -> separately authorized update

This is a routing decision rather than a risk score. A small schema change does not become application-only, and a successful CI run does not implicitly dispatch either delivery workflow.

Where Responsibilities Live

`.github/workflows`

Workflows own event policy, job ordering, selected-source admission, GitHub permissions, protected environments, OIDC handoff, and summaries. They should orchestrate repository-owned commands instead of becoming a second implementation of application or infrastructure logic.

`packages/cli` and `bin`

The wavemap CLI is the discoverable operator trunk. Route definitions lead to shell wrappers; wrappers own external process execution, filesystem safety, environment setup, dry-run or --execute gates, and calls into typed operations.

`infra/operations`

The operations package owns typed parsing, validation, planning, bundle construction, deployment-contract handling, topology projection, and sanitized receipt shapes. It does not own GitHub credentials, public CLI compatibility, or Pulumi resources.

`infra/pulumi`

The Wavemap Pulumi project owns the workload resource graph and stable outputs. It does not decide which application commit to deploy, silently mutate the database, or gain authority merely because its program compiles.

Documentation and working notes

Curated docs teach the current architecture and safe reading path. Working notes retain active plans, exact run history, and unresolved questions. Neither replaces code-owned contracts, provider readback, or live authorization.

Strategic Source Trail

Use these entry points to move from the mental model into implementation without trying to read the repository as one flat catalog.

Concern	Start Here	Follow Into
CI ownership	`.github/workflows/ci.yml`	`bin/ci/classify-ci-assurance-paths.sh`, root `package.json`, `turbo.json`, then the named package/app test scripts.
Application-only delivery	`.github/workflows/deploy-application-dev.yml`	`infra/operations/src/deployed-dev/application-delivery*`, `bin/dev-deploy`, then focused workflow and operations tests.
Reviewed operator delivery	`.github/workflows/deploy-dev.yml`	`bin/dev-deploy/resolve-deployed-dev-workflow-profile.sh`, `infra/operations/src/deployed-dev/workflow-profile.ts`, the public CLI routes, then leaf deploy/smoke wrappers and profile tests.
Infrastructure change	`bin/infra/pulumi-stack.sh`	`infra/pulumi/index.ts`, `infra/pulumi/src/providers/aws`, saved-plan audit source, then launcher and Pulumi tests.
State foundation	Tendril `infra/foundation/src/state-backend.ts`	Tendril backend-policy tests and Wavemap’s guarded launcher; product workload source remains in this repository.
Data safety	`apps/wavemap-back-end/src/db/databaseSafety.ts`	DB-backed Vitest configuration, reset helpers, migrations/seeds, and the dedicated CI service contract.
Docs publication	`.github/workflows/deploy-docs.yml`	`.github/actions/prepare-docs-deploy-cloud-job`, `bin/docs-deploy`, `infra/operations/src/docs-deploy`, and docs smoke source.

When following a row, read the immediate tests beside the owning source before moving outward. Tests usually reveal the boundary faster than searching for every caller, and they show which behavior maintainers consider contractual.