Monorepo Map

Wavemap is a pnpm-workspaces monorepo. The repo is organized around runnable apps, shared packages, and infrastructure or operations workspaces. Use this page as the first map before dropping into architecture pages, package source, or working notes.

This page is intentionally descriptive. Code, package manifests, route contracts, validators, and scripts remain the source of truth for exact behavior.

Workspace Shape

Area	Path	Owns
Front end	`apps/wavemap-front-end`	Next.js app routes, UI workflows, reusable UI components, client API hooks, browser runtime behavior.
Back end	`apps/wavemap-back-end`	API routes, auth/session behavior, database-backed handlers, media adapters, email rendering.
Docs site	`apps/wavemap-docs`	Astro/Starlight documentation, public docs IA, docs build, and curated publication boundary.
API contracts	`packages/api-contracts`	Route constants, DTOs, API envelopes, query contracts, roles, permissions, and domain code surfaces.
i18n	`packages/i18n`	Locale and namespace contracts, translation resources, runtime helpers, assets, and i18n guardrails.
Shared utilities	`packages/shared-utils`	Cross-cutting constants, types, utilities, and shared tool configuration.
Public CLI	`packages/cli`	The public `wavemap` / `wm` command route table, help text, and route-contract tests.
Typed operations	`infra/operations`	Operational planning, validation, summaries, projections, helper outputs, and typed leaf CLIs.
Infrastructure as code	`infra/pulumi`	Cloud resources, stack outputs, provider assemblies, IAM shapes, DNS, runtime, and docs hosting.
Root workspace orchestration	repo root	pnpm workspace scripts, Turborepo task wiring, CI-facing commands, and release-age guardrails.

How The Pieces Connect

@wavemap/api-contracts is the main application boundary between the front end and back end. When a route, DTO, API envelope, query shape, permission code, or frontend route constant needs to be shared across apps, it should usually live there instead of being redefined in each app.

@wavemap/i18n owns localization as a platform package, not as a front-end-only folder. The front end consumes the client runtime and locale resources, the back end consumes server error and email copy adapters, and CI uses the package guardrails to catch namespace, sheet, ICU, and domain-code drift.

@wavemap/shared-utils sits below the product-specific packages. It is the right home for reusable constants, types, utilities, and shared tooling configuration when the concept is not owned by API contracts or i18n.

@wavemap/cli is the public command product. It should stay focused on route registration, command names, help text, and compatibility guarantees. Live execution belongs to shell wrappers and typed planning belongs to @wavemap/operations.

@wavemap/operations is the typed operations layer. It parses, validates, plans, summarizes, and projects operational data, but it should not become the public CLI package or the owner of cloud credentials.

infra/pulumi owns infrastructure resources and durable cloud output contracts. Operations code and shell wrappers can consume Pulumi outputs, but they should not silently redefine resource names, runtime contracts, DNS shapes, or IAM expectations outside the infrastructure boundary.

Operating Model

The monorepo works best as a set of owned boundaries that meet through explicit contracts. A change should move outward only when another package, app, workflow, or operator path needs to depend on it.

Shared API contracts come first when behavior crosses the front-end/back-end boundary.
Apps own the route handlers, UI workflows, hooks, adapters, and page-specific decisions that make those contracts real.
Platform packages own repeated cross-cutting concerns such as localization, DTOs, shared query controls, permission codes, and reusable tooling configuration.
The public CLI owns command names and compatibility promises, while typed operations and shell wrappers own planning, validation, live execution, and workflow handoff.
Pulumi owns the cloud resource graph and stable infrastructure outputs; deployment code consumes those outputs without redefining cloud facts.
The docs site owns curated memory. Roadmaps and working notes can carry proof history and branch context, but stable lessons should graduate into focused developer, operations, or admin reference pages.

Change Flow

Most cross-app feature work follows the same broad shape:

Identify the owning boundary first: app-local UI, backend route, shared API contract, i18n resource, operations command, or infrastructure resource.
Add or adjust shared contracts before wiring consumers when the change crosses the front-end/back-end boundary.
Keep route handlers, workflow hooks, and UI components close to the app that owns the behavior.
Use @wavemap/i18n when user-facing copy needs locale, namespace, backend error, email, or reusable component label support.
Add the narrowest useful tests at the layer that owns the risk.
Promote stable lessons into docs only after the implementation pattern has stopped moving quickly.

Boundary Rules

Do not make app code rediscover shared DTOs, routes, role codes, permission codes, or query-control contracts.
Do not make reusable UI components import Wavemap translation keys directly; pass display-ready labels from page or domain adapters.
Do not make @wavemap/operations depend on @wavemap/cli; the public command surface should be able to route to operations helpers without becoming their dependency.
Do not persist emulator names as media storage providers. Emulators are execution targets; provider identity belongs to the persisted storage locator.
Do not publish raw cloud evidence, provider inventories, Pulumi exports, workflow logs, or live identifiers into the docs site.
Do not use working notes as durable reference once a convention is stable enough for future developers or operators.