ADR-004: Frontend apps use <audience>-web naming

• Status: Accepted
• Date: 2026-05-23
• Deciders: CTO / Founding Engineering

Context

Frontends were originally named after the team that requested them or after the database role they served:

• apps/admin (platform admin)
• apps/business (employer admin)
• apps/client (employee app)
• apps/fi (financial institutions)
• apps/bnpl-partner (BNPL merchants)
• apps/docs (public documentation)

A new engineer can't tell from the name who uses client (vs customer? vs consumer?) or what fi is. The names also collide with code semantics — client is an overloaded word in any web codebase.

Decision

Every frontend app folder is named <audience>-web:

Old	New	Audience
apps/admin	apps/admin-web	platform admin team
apps/business	apps/employer-web	employer / business admin
apps/client	apps/employee-web	end-user employee
apps/fi	apps/fi-web	financial-institution staff
apps/bnpl-partner	apps/merchant-web	BNPL merchant / retailer
apps/docs	apps/docs-web	public documentation site

E2E suffix: <audience>-web-e2e. Nx project names match folder names (admin-web, employer-web, …). Dev ports keep their existing assignment (4200/4201/4202/4203/4204), docs-web gets 4205.

Alternatives considered

• Keep current names. Rejected — onboarding tax compounds; client is the worst offender semantically.
• Use -app suffix instead of -web. Rejected — these are web apps specifically; future mobile clients would be <audience>-mobile.
• Drop the suffix and just use the audience (admin/, employer/, employee/). Rejected — leaves no room for future per-audience non-web surfaces (mobile, kiosk, IVR).

Consequences

Positive

• A folder name answers "who uses this and how?" with no further reading.
• nx serve employee-web is unambiguous.
• A future employee-mobile slot exists without rename.

Negative

• Touches every CI matrix, deploy manifest, docker-compose service block, dev-port reference, and every existing import path that hard-coded a name.
• One disruptive PR. Mitigated by doing it once and locking with this ADR.

Follow-ups

• All grep-found references to old names updated in this PR.
• Stale links in external docs (Notion, Linear, Slack pins) flagged in the restructure migration plan.
• A future <audience>-mobile/ could land at any time without further structural debate.