docs: correct Frontend Architecture: Feature-Oriented Boundaries in the beta README

Evidence: spikersoft-angular@master libraries/domain/blog/src/lib/avif-encoder.port.ts:38 declares AVIF_ENCODER in the domain lib.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
spikerjandCursor committed 2026-10-06 03:45:24 -04:00
1 parent 7fde29b97d
commit f1fe7a0cc1
1 file changed
+9 -9
+9 -9
View File
@@ -964,7 +964,7 @@ Beyond publishing, the app is self-contained: no S3 client, and every pipeline s
## Frontend Architecture: Feature-Oriented Boundaries
The Angular workspace was migrated through a multi-phase refactor (Phases 4–6, completed 2026-05-09 — see [`docs/architecture/inventory.md`](docs/architecture/inventory.md) and [`docs/architecture/boundaries.md`](docs/architecture/boundaries.md)) from a monolithic `libraries/tools/` lib into buildable libraries grouped by **layer** (84 `project.json` libraries today and growing). Each library has its own `ng-package.json`, `vitest.config.ts`, `project.json`, and tests run isolated. Lazy-loaded routes per feature → smaller initial bundle (the Phase 6 sub-phases collectively brought the gzipped `main.js` to ~302 kB).
The Angular workspace was migrated through a multi-phase refactor (Phases 4–6, completed 2026-05-09) from a monolithic `libraries/tools/` lib into buildable libraries grouped by **layer** (121 `project.json` libraries under `libraries/` today). Each library has its own `ng-package.json` and `project.json`. Tests run isolated; `platform/content-locale` is the one library without a `vitest.config.ts`. Lazy-loaded routes per feature → smaller initial bundle (the Phase 6 sub-phases collectively brought the gzipped `main.js` to ~302 kB). `docs/architecture/inventory.md` and `docs/architecture/boundaries.md` are not in the Angular tree; the enforced rule is [`eslint.config.cjs`](spikersoft-angular/eslint.config.cjs).
### Layers and clusters
@@ -972,11 +972,11 @@ Every library carries at least one `layer:*` tag in its `project.json`. The boun
| Cluster | Layer tag | Count | Purpose |
|---|---|---|---|
| [`libraries/domain/`](spikersoft-angular/libraries/domain/) | `layer:domain` | 11 | Pure data models + thin services bound to backend resources, **no UI**: `blog`, `book`, `child-account`, `fundraiser`, `geo`, `mrz`, `photograph`, `pre-registration`, `profile`, `sponsor`, `users` |
| [`libraries/features/`](spikersoft-angular/libraries/features/) | `layer:feature` | 32 | Top-level user-facing features that own routes/components/services: the `dev-tools-*` suite (20 tools — C#/Python/JavaScript/regex/x86/C/C++/SQL playgrounds, decompiler, encoding, conversions-monaco, image-to-avif/ico, qr-code, diff, diagram, blockly, duckdb, ipv4, quick-type), plus `art-studio`, `blog`, `child-account-dialog`, `fundraiser`, `games-clue-for-sql`, `geo-globe`, `parent-dashboard`, `photo-gallery`, `sponsor`, `sponsor-cards`, `status`, `trellis-3d-generator` (orphaned — no route; kept for reference, new modeling goes through Art Studio) |
| [`libraries/platform/`](spikersoft-angular/libraries/platform/) | `layer:platform` | 19 | Cross-cutting infrastructure consumed by features: `language-runner`, `lesson-catalog`, `progress-sync`, `pyodide-runtime`, `clang-runtime`, `monaco-editor`, `tool-storage`, `tool-file-menu`, `intro-tour`, `intro-launching`, `js-step-debugger`, `step-debugger-core`, `activity-tracking-api`/`-impl` (port + implementation split), `anon-session`, `content-locale`, `playground-visual-progress`, `loading`, `avif-encoder` |
| [`libraries/shared/`](spikersoft-angular/libraries/shared/) | `layer:shared` | 7 | Small reusable units that don't belong to a single feature/domain: `api-config`, `js-formatting-options`, `lesson-panes`, `lesson-platform`, `practice-decks`, `save-load-dialogs`, `utils/{crc32,file-hash}` |
| [`libraries/ui/`](spikersoft-angular/libraries/ui/) | `layer:ui` | 7 | Pure presentational atoms: `avatar-stack`, `award-chips`, `confirm-dialog`, `destination-chips`, `image-paste`, `mrz-crop`, `user-picker` |
| [`libraries/domain/`](spikersoft-angular/libraries/domain/) | `layer:domain` | 20 | Pure data models + thin services bound to backend resources, **no UI**: `art-studio`, `blog`, `book`, `changelog`, `child-account`, `climbing`, `family`, `fundraiser`, `geo`, `guides`, `horticulture`, `mail-metrics`, `mrz`, `photograph`, `pre-registration`, `profile`, `sanctions`, `skills`, `sponsor`, `users` |
| [`libraries/features/`](spikersoft-angular/libraries/features/) | `layer:feature` | 47 | Top-level user-facing features that own routes/components/services: the `dev-tools-*` suite (20 tools — C#/Python/JavaScript/`reg-ex`/x86/C/C++/SQL playgrounds, decompiler, encoding, conversions-monaco, image-to-avif, `img-to-ico`, qr-code, `difference`, diagram, blockly, duckdb, ipv4, quick-type), plus `art-studio`, `blog`, `changelog`, `child-account-dialog`, `climbing`, `family`, `finance-dashboard`, `fundraiser`, `games-clue-for-sql`, `geo-globe`, `guides`, `hardware-dashboard`, `horticulture`, `horticulture-seller`, `mail-admin`, `member-dashboard`, `parent-dashboard`, `photo-gallery`, `sanctions`, `sky-viewer`, `sponsor`, `sponsor-cards`, `staff-dashboard`, `status`, `trellis-3d-generator` (orphaned — no route; kept for reference, new modeling goes through Art Studio), `typing`, `velocity` |
| [`libraries/platform/`](spikersoft-angular/libraries/platform/) | `layer:platform` | 23 | Cross-cutting infrastructure consumed by features: `language-runner`, `lesson-catalog`, `progress-sync`, `pyodide-runtime`, `clang-runtime`, `monaco-editor`, `tool-storage`, `tool-file-menu`, `intro-tour`, `js-step-debugger`, `step-debugger-core`, `activity-tracking-api`/`-impl` (port + implementation split), `anon-session`, `content-locale`, `currency`, `error-reporting`, `page-meta`, `playground-visual-progress`, `quick-actions`, `loading`, `avif-encoder`, `typing-sync` |
| [`libraries/shared/`](spikersoft-angular/libraries/shared/) | `layer:shared` | 11 | Small reusable units that don't belong to a single feature/domain: `api-config`, `auth-roles`, `js-formatting-options`, `lesson-panes`, `lesson-platform`, `money`, `practice-decks`, `save-load-dialogs`, `staff-approvals`, `typing-core`, and `utils/crc32` |
| [`libraries/ui/`](spikersoft-angular/libraries/ui/) | `layer:ui` | 12 | Pure presentational atoms: `avatar-stack`, `award-chips`, `confirm-dialog`, `dashboard-charts`, `destination-chips`, `image-paste`, `inbox-layout`, `mrz-crop`, `password-strength`, `stat-tile`, `status-visuals`, `user-picker` |
| [`libraries/game/`](spikersoft-angular/libraries/game/) | `layer:game` | 3 | Game-runtime libs that pair a feature with heavy runtime deps: `gl-hud`, `hex-tower-defence`, `wasm-voxel` |
| Top-level legacy | various | 5 | Pre-Phase-4 libs that haven't been re-clustered into the new directories yet but already carry the right layer tag: `keycloak-admin` (`layer:feature`), `marks-site-models` + `spikersoft-models` (`layer:domain`), `spikersoft-environment` (`layer:platform`), `spikersoft-theme` (`layer:ui`) |
@@ -1026,16 +1026,16 @@ flowchart TB
game --> shared
```
The arrows go **only downward**. A `domain` lib that tries to import from `feature` or `platform` fails CI; `platform` cannot import `feature`; `shared` cannot import anything but `shared`. This is what the boundary refactor bought: the dep graph is now mechanically prevented from collapsing back into the old "everything imports `tools`" shape.
Same-layer imports are allowed (`feature` may import `feature`, and the same for `ui`, `domain`, `platform`, `game`, and `shared`). A `domain` lib that tries to import from `feature` or `platform` fails CI; `platform` cannot import `feature`; `shared` cannot import anything but `shared`. This is what the boundary refactor bought: the dep graph is now mechanically prevented from collapsing back into the old "everything imports `tools`" shape.
### Cross-cluster ports
Where a feature genuinely needs to consume a service from another cluster without violating the arrows, the lib pair uses a **port** (an injection token) declared in `shared/lesson-platform` and provided at the wrapping shell. Examples:
- [`PROGRESS_SYNC_PORT`](spikersoft-angular/libraries/shared/lesson-platform/src/lib/progress-sync-port.ts) — consumed by `platform/language-runner` so the shared playground shell never hard-imports the Monaco-coupled `ProgressSyncService` concrete (the `feature/dev-tools-csharp-runner` shell wires it up at provider time).
- `AVIF_ENCODER` port — `domain/blog` and `feature/dev-tools-image-to-avif` consume the encoder through a port declared in `shared`, so the domain lib never depends directly on `platform/avif-encoder`.
- `AVIF_ENCODER` port — declared in `domain/blog` (`avif-encoder.port.ts`). `domain/blog` consumes it, and so does `feature/horticulture-seller`. The domain lib does not depend on `platform/avif-encoder`.
If a new feature seems to require an arrow the layering forbids, the right answer is almost always to extract a port or a contract type into `shared/lesson-platform` (or its sibling `shared/api-config`) rather than to widen the rule. See [`docs/architecture/boundaries.md`](docs/architecture/boundaries.md) for the canonical write-up of the rule, baseline counts, and the burn-down protocol that closed the last ~22 violations.
If a new feature seems to require an arrow the layering forbids, the right answer is almost always to extract a port or a contract type into `shared/lesson-platform` (or its sibling `shared/api-config`) rather than to widen the rule. The rule is error-level in `eslint.config.cjs`. One violation remains, exempted with an inline disable.
---