feat: enforce frontend architecture boundaries

.dependency-cruiser.cjs

@@ -0,0 +1,49 @@
+/** @type {import("dependency-cruiser").IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: "domain-is-framework-neutral",
+      severity: "error",
+      from: { path: "^src/domain" },
+      to: {
+        path: "^(src/(application|presentation|adapters|bootstrap)|react|react-dom|@tanstack)",
+      },
+    },
+    {
+      name: "application-does-not-know-concrete-runtime",
+      severity: "error",
+      from: { path: "^src/application" },
+      to: {
+        path: "^(src/(presentation|adapters|bootstrap)|react|react-dom|@tanstack)",
+      },
+    },
+    {
+      name: "presentation-does-not-know-adapters",
+      severity: "error",
+      from: { path: "^src/presentation" },
+      to: { path: "^(src/(adapters|bootstrap)|@tanstack)" },
+    },
+    {
+      name: "adapters-do-not-know-presentation",
+      severity: "error",
+      from: { path: "^src/adapters" },
+      to: { path: "^src/(presentation|bootstrap)" },
+    },
+    {
+      name: "no-circular-dependencies",
+      severity: "error",
+      from: {},
+      to: { circular: true },
+    },
+  ],
+  options: {
+    doNotFollow: { path: "node_modules" },
+    exclude: {
+      path: "^(dist|artifacts|tests/fixtures)",
+    },
+    enhancedResolveOptions: {
+      exportsFields: ["exports"],
+      conditionNames: ["import", "require", "node", "default"],
+    },
+  },
+};

config/architecture/layers.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "layers": {
+    "domain": {
+      "root": "src/domain",
+      "mayImport": ["src/domain"]
+    },
+    "application": {
+      "root": "src/application",
+      "mayImport": ["src/application", "src/domain", "src/contracts"]
+    },
+    "presentation": {
+      "root": "src/presentation",
+      "mayImport": ["src/presentation", "src/application", "src/domain", "src/contracts"]
+    },
+    "adapters": {
+      "root": "src/adapters",
+      "mayImport": ["src/adapters", "src/application", "src/domain", "src/contracts"]
+    },
+    "bootstrap": {
+      "root": "src/bootstrap",
+      "mayImport": ["src"]
+    }
+  },
+  "forbidden": [
+    ["domain", "application"],
+    ["domain", "presentation"],
+    ["domain", "adapters"],
+    ["domain", "bootstrap"],
+    ["application", "presentation"],
+    ["application", "adapters"],
+    ["application", "bootstrap"],
+    ["presentation", "adapters"],
+    ["presentation", "bootstrap"],
+    ["adapters", "presentation"],
+    ["adapters", "bootstrap"]
+  ]
+}

docs/architecture/layers.md

@@ -0,0 +1,34 @@
+# Clean Architecture layer contract
+
+The import direction is `domain <- application <- presentation`; concrete
+adapters implement application-owned ports and are assembled only in
+`src/bootstrap`.
+
+| Layer | Owns | May depend on |
+| --- | --- | --- |
+| `domain` | framework-neutral models and pure policies | domain siblings |
+| `application` | use cases, ports, orchestration, view-models | domain and application siblings |
+| `presentation` | routes, components, user interaction and view state | application public API and shared UI |
+| `adapters` | browser and third-party implementations of application ports | application ports and limited domain values |
+| `bootstrap` | runtime configuration, adapter construction and React mount | all selected runtime modules |
+
+The following edges are forbidden:
+
+- domain to application, presentation, adapters, bootstrap, React, or browser globals
+- application to presentation, concrete adapters, bootstrap, React, or browser globals
+- presentation to concrete adapters, raw DTO schemas, or storage implementations
+- an adapter to presentation, bootstrap internals, or another concrete adapter
+
+`bootstrap` contains composition only. Business rules and page-specific
+orchestration belong to domain/application.
+
+Architecture reports use this shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedAt": "ISO-8601",
+  "rules": [{ "name": "rule-id", "severity": "error", "violations": 0 }],
+  "summary": { "errors": 0, "warnings": 0 }
+}
+```

docs/testing/taxonomy.md

@@ -0,0 +1,24 @@
+# Test and evidence taxonomy
+
+Each gate is blocking in its declared scope. Failures are not downgraded with
+`continue-on-error` or warning-only scripts.
+
+| Level | Command | Evidence |
+| --- | --- | --- |
+| runtime schema | `pnpm test:runtime-schema` | `artifacts/tests/runtime-schema.xml` |
+| unit | `pnpm test:unit` | `artifacts/tests/unit.xml` |
+| component | `pnpm test:component` | `artifacts/tests/component.xml` |
+| integration | `pnpm test:integration` | `artifacts/tests/integration.xml` |
+| end-to-end | `pnpm test:e2e` | `artifacts/tests/e2e/` |
+| accessibility | `pnpm test:a11y` | `artifacts/tests/a11y.json` |
+
+A control is verified only when a positive fixture passes and its deliberately
+failing negative fixture is rejected. Generated evidence is retained by CI;
+the repository tracks only the evidence directory structure.
+
+Promotion is an AND graph:
+
+1. merge gates
+2. merge gates plus release gates
+3. release gates plus rollback/runbook drills
+4. production promotion plus eligible field Web Vitals evidence

eslint.config.js

@@ -0,0 +1,101 @@
+import eslint from "@eslint/js";
+import globals from "globals";
+
+const layerPatterns = {
+  domain: [
+    "**/application/**",
+    "**/presentation/**",
+    "**/adapters/**",
+    "**/bootstrap/**",
+    "react",
+    "react-dom",
+    "@tanstack/**",
+  ],
+  application: [
+    "**/presentation/**",
+    "**/adapters/**",
+    "**/bootstrap/**",
+    "react",
+    "react-dom",
+    "@tanstack/**",
+  ],
+  presentation: ["**/adapters/**", "**/bootstrap/**", "@tanstack/**"],
+  adapters: ["**/presentation/**", "**/bootstrap/**"],
+};
+
+function restrictedImports(patterns) {
+  return ["error", { patterns }];
+}
+
+export default [
+  {
+    ignores: [
+      "dist/**",
+      "node_modules/**",
+      "artifacts/**",
+      "tests/fixtures/typecheck/**",
+      "tests/fixtures/architecture/forbidden/**",
+    ],
+  },
+  eslint.configs.recommended,
+  {
+    files: ["**/*.{js,jsx,mjs}"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+      },
+    },
+  },
+  {
+    files: ["src/domain/**/*.{js,jsx}"],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.domain),
+      "no-restricted-globals": ["error", "window", "document", "localStorage", "fetch"],
+    },
+  },
+  {
+    files: ["src/application/**/*.{js,jsx}"],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.application),
+      "no-restricted-globals": ["error", "window", "document", "localStorage", "fetch"],
+    },
+  },
+  {
+    files: ["src/presentation/**/*.{js,jsx}"],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.presentation),
+    },
+  },
+  {
+    files: ["src/adapters/**/*.{js,jsx}"],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.adapters),
+    },
+  },
+  {
+    files: ["tests/**/*.{js,jsx}"],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ["tests/fixtures/architecture/forbidden/**/*.{js,jsx}"],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/adapters/**",
+        "@tanstack/**",
+        "react",
+        "react-dom",
+      ]),
+    },
+  },
+];

package.json

@@ -12,19 +12,40 @@
     "dev": "vite",
     "build": "vite build && node scripts/generate-build-manifest.mjs",
     "preview": "vite preview",
+    "lint": "eslint src scripts tests vite.config.js vitest.config.js playwright.config.js --max-warnings=0",
+    "check:architecture": "node scripts/check-architecture.mjs",
     "check:types": "tsc --allowJs --checkJs --noEmit",
-    "check:types:fixture": "tsc --ignoreConfig --allowJs --checkJs --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext tests/fixtures/typecheck/invalid-port-call.js"
+    "check:types:fixture": "tsc --allowJs --checkJs --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext tests/fixtures/typecheck/invalid-port-call.js",
+    "test:runtime-schema": "vitest run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
+    "test:unit": "vitest run tests/unit --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/unit.xml",
+    "test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml",
+    "test:integration": "vitest run tests/integration --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/integration.xml",
+    "test:e2e": "playwright test",
+    "test:a11y": "playwright test --grep @a11y",
+    "test:all": "pnpm test:runtime-schema && pnpm test:unit && pnpm test:component && pnpm test:integration"
   },
   "dependencies": {
     "react": "19.2.8",
     "react-dom": "19.2.8"
   },
   "devDependencies": {
+    "@axe-core/playwright": "4.12.1",
+    "@eslint/js": "10.0.1",
+    "@playwright/test": "1.62.0",
+    "@testing-library/jest-dom": "7.0.0",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "14.6.1",
     "@types/node": "24.13.3",
     "@types/react": "19.2.8",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "6.0.4",
+    "dependency-cruiser": "18.1.0",
+    "eslint": "10.8.0",
+    "globals": "17.7.0",
+    "jsdom": "29.1.1",
+    "msw": "2.15.0",
     "typescript": "7.0.2",
-    "vite": "8.1.5"
+    "vite": "8.1.5",
+    "vitest": "4.1.10"
   }
 }

playwright.config.js

@@ -0,0 +1,23 @@
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  outputDir: "./artifacts/tests/e2e/results",
+  reporter: [
+    ["list"],
+    ["html", { outputFolder: "./artifacts/tests/e2e/report", open: "never" }],
+  ],
+  use: {
+    baseURL: "http://127.0.0.1:5173",
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+  },
+  webServer: {
+    command: "pnpm dev --host 127.0.0.1",
+    url: "http://127.0.0.1:5173",
+    reuseExistingServer: !process.env.CI,
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+  ],
+});

pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+allowBuilds:
+  msw: true
+minimumReleaseAgeExclude:
+  - '@playwright/test@1.62.0'
+  - playwright-core@1.62.0
+  - playwright@1.62.0
+  - eslint@10.8.0

scripts/check-architecture.mjs

@@ -0,0 +1,69 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+
+await mkdir("artifacts/quality", { recursive: true });
+
+const pnpmCli = /** @type {string} */ (process.env.npm_execpath);
+
+if (!pnpmCli) {
+  throw new Error("check:architecture must run through the pnpm script");
+}
+
+/** @param {string[]} arguments_ */
+function runPnpm(arguments_) {
+  return spawnSync(process.execPath, [pnpmCli, ...arguments_], {
+    encoding: "utf8",
+  });
+}
+
+const production = runPnpm(
+  [
+    "exec",
+    "depcruise",
+    "src",
+    "--config",
+    ".dependency-cruiser.cjs",
+    "--output-type",
+    "json",
+  ],
+);
+
+await writeFile(
+  "artifacts/quality/dependency-report.json",
+  production.stdout || JSON.stringify({ summary: { errors: 1 } }),
+);
+
+if (production.status !== 0) {
+  process.stderr.write(
+    production.error?.message ?? production.stderr ?? production.stdout ?? "failed",
+  );
+  process.exit(production.status ?? 1);
+}
+
+const allowed = runPnpm(
+  [
+    "exec",
+    "eslint",
+    "tests/fixtures/architecture/allowed",
+    "--no-ignore",
+    "--max-warnings=0",
+  ],
+);
+
+const forbidden = runPnpm(
+  [
+    "exec",
+    "eslint",
+    "tests/fixtures/architecture/forbidden",
+    "--no-ignore",
+    "--max-warnings=0",
+  ],
+);
+
+if (allowed.status !== 0 || forbidden.status === 0) {
+  process.stderr.write(allowed.stderr || allowed.stdout);
+  process.stderr.write(forbidden.stderr || forbidden.stdout);
+  process.exit(1);
+}
+
+process.stdout.write("Architecture fixtures: allowed PASS, forbidden rejected\n");

src/application/create-application.js

@@ -0,0 +1,40 @@
+/**
+ * Application facade factory. Concrete dependencies are supplied by bootstrap.
+ *
+ * @param {{
+ *   resources: {
+ *     query: import("./ports/resource-ports.js").ResourceQueryPort<unknown, unknown>,
+ *     command: import("./ports/resource-ports.js").ResourceCommandPort<unknown, unknown>
+ *   },
+ *   cache: import("./ports/query-cache-port.js").QueryCachePort,
+ *   storage: import("./ports/storage-port.js").StoragePort,
+ *   telemetry: import("./ports/telemetry-port.js").TelemetryPort
+ * }} ports
+ */
+export function createApplication(ports) {
+  /**
+   * @param {unknown} query
+   * @param {import("./ports/resource-ports.js").RequestContext} [context]
+   */
+  function queryResources(query, context) {
+    return ports.resources.query.execute(query, context);
+  }
+
+  /**
+   * @param {unknown} command
+   * @param {import("./ports/resource-ports.js").RequestContext} [context]
+   */
+  function commandResources(command, context) {
+    return ports.resources.command.execute(command, context);
+  }
+
+  return Object.freeze({
+    resources: Object.freeze({
+      query: queryResources,
+      command: commandResources,
+    }),
+    cache: ports.cache,
+    storage: ports.storage,
+    telemetry: ports.telemetry,
+  });
+}

src/application/ports/auth-session-port.js

@@ -0,0 +1,16 @@
+/**
+ * @typedef {"authenticated" | "unauthenticated" | "recovery-pending" | "integration-failed"} SessionState
+ */
+
+/**
+ * The session is opaque: credentials are attached without exposing tokens.
+ *
+ * @typedef {{
+ *   getState(): SessionState,
+ *   attach(request: Request): Promise<Request>,
+ *   recover(): Promise<"restored" | "no-session">,
+ *   onUnauthenticated(): void
+ * }} AuthSessionPort
+ */
+
+export {};

src/application/ports/clock-port.js

@@ -0,0 +1,29 @@
+/**
+ * @typedef {{
+ *   now(): number,
+ *   sleep(milliseconds: number, signal?: AbortSignal): Promise<void>
+ * }} ClockPort
+ */
+
+/** @type {ClockPort} */
+export const systemClock = Object.freeze({
+  now: () => Date.now(),
+  sleep(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(signal.reason);
+        return;
+      }
+
+      const timer = setTimeout(resolve, milliseconds);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          reject(signal.reason);
+        },
+        { once: true },
+      );
+    });
+  },
+});

src/application/ports/query-cache-port.js

@@ -0,0 +1,9 @@
+/**
+ * @typedef {{
+ *   read(key: readonly unknown[]): unknown,
+ *   write(key: readonly unknown[], value: unknown): void,
+ *   invalidate(namespace: readonly unknown[]): Promise<void>
+ * }} QueryCachePort
+ */
+
+export {};

src/application/ports/release-info-port.js

@@ -0,0 +1,13 @@
+/**
+ * @typedef {{
+ *   getCurrent(): Promise<{
+ *     buildId: string,
+ *     configSchemaVersion: string,
+ *     apiContractVersion: string,
+ *     assetManifestHash: string,
+ *     releaseId: string
+ *   }>
+ * }} ReleaseInfoPort
+ */
+
+export {};

src/application/ports/resource-ports.js

@@ -0,0 +1,28 @@
+/**
+ * @template Query
+ * @template Model
+ * @typedef {{ execute(query: Query, context?: RequestContext): Promise<Result<Model>> }} ResourceQueryPort
+ */
+
+/**
+ * @template Command
+ * @template Model
+ * @typedef {{ execute(command: Command, context?: RequestContext): Promise<Result<Model>> }} ResourceCommandPort
+ */
+
+/**
+ * @typedef {{
+ *   operationId: string,
+ *   routeId: string,
+ *   signal?: AbortSignal,
+ *   idempotencyKey?: string
+ * }} RequestContext
+ */
+
+/**
+ * @template Value
+ * @typedef {{ ok: true, value: Value, meta?: Record<string, unknown> } |
+ *   { ok: false, error: unknown }} Result
+ */
+
+export {};

src/application/ports/storage-port.js

@@ -0,0 +1,9 @@
+/**
+ * @typedef {{
+ *   read(logicalName: string): { ok: true, value: unknown } | { ok: false, error: unknown },
+ *   write(logicalName: string, value: unknown): { ok: true } | { ok: false, error: unknown },
+ *   remove(logicalName: string): { ok: true } | { ok: false, error: unknown }
+ * }} StoragePort
+ */
+
+export {};

src/application/ports/telemetry-port.js

@@ -0,0 +1,5 @@
+/**
+ * @typedef {{ emit(eventName: string, attributes: Record<string, unknown>): void }} TelemetryPort
+ */
+
+export {};

src/bootstrap/composition-root.js

@@ -0,0 +1,23 @@
+import { createApplication } from "../application/create-application.js";
+
+/**
+ * This is the only module allowed to join concrete adapters to application
+ * ports. Boot phases are explicit so failures can stop before product mount.
+ *
+ * @param {{
+ *   loadConfig(): Promise<Record<string, unknown>>,
+ *   loadRelease(config: Record<string, unknown>): Promise<Record<string, unknown>>,
+ *   createAdapters(context: {
+ *     config: Record<string, unknown>,
+ *     release: Record<string, unknown>
+ *   }): Promise<Parameters<typeof createApplication>[0]>
+ * }} factories
+ */
+export async function createCompositionRoot(factories) {
+  const config = await factories.loadConfig();
+  const release = await factories.loadRelease(config);
+  const ports = await factories.createAdapters({ config, release });
+  const application = createApplication(ports);
+
+  return Object.freeze({ config, release, ports, application });
+}

tests/component/bootstrap-shell.test.jsx

@@ -0,0 +1,17 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+function TestShell() {
+  return <main aria-label="application shell">ready</main>;
+}
+
+describe("component test level", () => {
+  it("renders an accessible application shell", () => {
+    render(<TestShell />);
+    expect(screen.getByRole("main", { name: "application shell" })).toHaveTextContent(
+      "ready",
+    );
+  });
+});

tests/e2e/app-shell.spec.js

@@ -0,0 +1,8 @@
+import { expect, test } from "@playwright/test";
+
+test("boots the public app shell", async ({ page }) => {
+  await page.goto("/");
+  await expect(page.getByRole("heading", { level: 1 })).toHaveText(
+    "Clean Architecture Frontend",
+  );
+});

tests/fixtures/architecture/allowed/presentation-facade.js

@@ -0,0 +1,3 @@
+import { createApplication } from "../../../../src/application/create-application.js";
+
+export const applicationFactory = createApplication;

tests/fixtures/architecture/forbidden/application-imports-tanstack.js

@@ -0,0 +1,3 @@
+import { QueryClient } from "@tanstack/react-query";
+
+export const invalidClient = new QueryClient();

tests/fixtures/architecture/forbidden/domain-imports-react.js

@@ -0,0 +1,3 @@
+import React from "react";
+
+export const invalidDomainValue = React.createElement("div");

tests/fixtures/architecture/forbidden/presentation-imports-adapter.js

@@ -0,0 +1,3 @@
+import "../../../../src/adapters/http/client.js";
+
+export const invalidEdge = true;

tests/integration/http-boundary.test.js

@@ -0,0 +1,23 @@
+import { HttpResponse, http } from "msw";
+import { setupServer } from "msw/node";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+
+const server = setupServer(
+  http.get("https://example.test/health", () =>
+    HttpResponse.json({ success: true, data: { status: "ok" } }),
+  ),
+);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe("integration test level", () => {
+  it("uses MSW to isolate the HTTP boundary", async () => {
+    const response = await fetch("https://example.test/health");
+    await expect(response.json()).resolves.toEqual({
+      success: true,
+      data: { status: "ok" },
+    });
+  });
+});

tests/setup.js

@@ -0,0 +1,7 @@
+import "@testing-library/jest-dom/vitest";
+import { cleanup } from "@testing-library/react";
+import { afterEach } from "vitest";
+
+afterEach(() => {
+  cleanup();
+});

tests/unit/system-clock.test.js

@@ -0,0 +1,13 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { systemClock } from "../../src/application/ports/clock-port.js";
+
+describe("systemClock", () => {
+  it("resolves after the requested duration", async () => {
+    vi.useFakeTimers();
+    const sleeper = systemClock.sleep(250);
+    await vi.advanceTimersByTimeAsync(250);
+    await expect(sleeper).resolves.toBeUndefined();
+    vi.useRealTimers();
+  });
+});

vitest.config.js

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: false,
+    setupFiles: ["./tests/setup.js"],
+    restoreMocks: true,
+    clearMocks: true,
+    mockReset: true,
+    testTimeout: 10_000,
+    coverage: {
+      reporter: ["text", "json-summary"],
+    },
+  },
+});