feat(frontend): scaffold Angular 21 project with FastAPI SPA serving by Olino3 · Pull Request #33 · Olino3/LEDMatrix

Olino3 · 2026-03-20T18:14:44Z

Summary

Scaffold Angular 21 project in frontend/ with standalone components, SCSS, routing, and ESLint
Wire FastAPI to serve the built SPA via a catch-all route that serves static files and falls back to index.html for client-side routing
Add dev proxy (proxy.conf.json) routing /api/v3 and /stream to FastAPI at port 5000
Add environment file switching (fileReplacements in angular.json) for dev/prod builds
Create scripts/dev/run_frontend_dev.sh and make frontend-dev to run both servers together
Update CLAUDE.md with Angular dev commands and conventions

Tickets closed

FRONT-001 — Angular project scaffold
SPIKE-FRONT-001 — Node.js in distrobox (already available via shared NVM)
SPIKE-FRONT-002 — Angular environment file switching (wired fileReplacements)
SPIKE-FRONT-003 — Dev server proxy verification (created dev script)

Key decisions

Angular 21 (not 17 as originally spec'd) — latest stable, standalone components by default
Single catch-all route instead of StaticFiles mount — avoids Starlette mount/route precedence conflicts
spa_dist_dir computed inside create_app() — enables test patching via PROJECT_ROOT
Angular commands run on host — Node.js available via shared NVM, no distrobox needed

Test plan

6 new tests in test/test_api_spa_mount.py — all passing
Full test suite (1297 tests) — no regressions
ng build produces production bundle at frontend/dist/ledmatrix/browser/index.html
All 4 npm scripts present: start, build, test, lint
Proxy config validates as valid JSON
Existing HTMX pages at /v3/, API at /api/v3/, docs at /docs all preserved

…kets Update ROADMAP.md to reflect current version v2.0.0 with Phases 1 and 2 marked complete. Add 13 sprint tickets for Phase 3 frontend modernization (Angular + PrimeNG): 8 core tickets plus 5 SPIKEs.

Tests verify Angular SPA catch-all route serves index.html for client-side routing, serves static assets, and does not intercept reserved paths (/api/v3, /docs, /v3, /static).

SPIKE-FRONT-001: Node.js v24 available in both environments via shared NVM. Angular commands run on the host — no distrobox needed. Updated CLAUDE.md with Angular dev commands and workflow.

SPIKE-FRONT-002: Added fileReplacements to angular.json production config to swap environment.ts with environment.prod.ts at build time. Verified both production and development builds succeed.

SPIKE-FRONT-003: Created scripts/dev/run_frontend_dev.sh and make frontend-dev target. Starts both FastAPI (port 5000) and Angular dev server (port 4200) with proxy forwarding.

Copilot

Pull request overview

This PR introduces an Angular 21 frontend scaffold under frontend/ and wires the existing FastAPI app to serve the built SPA (static assets + index.html fallback) while preserving the current HTMX /v3 pages and /api/v3 endpoints during the migration.

Changes:

Add an Angular 21 standalone-component project scaffold with ESLint, Prettier, proxy config, and env switching.
Add FastAPI SPA catch-all serving from frontend/dist/ledmatrix/browser/ with static-file support and client-side-routing fallback.
Add a combined dev workflow (scripts/dev/run_frontend_dev.sh + make frontend-dev) and update sprint/planning docs.

Reviewed changes

Copilot reviewed 45 out of 48 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`test/test_api_spa_mount.py`	Adds tests for FastAPI SPA catch-all behavior and non-interception of reserved routes.
`src/api/main.py`	Adds SPA serving logic (static asset serving + `index.html` fallback) to the FastAPI app factory.
`scripts/dev/run_frontend_dev.sh`	Convenience script to run FastAPI + Angular dev server together.
`Makefile`	Adds `frontend-dev` target to run the combined dev script.
`frontend/angular.json`	Angular workspace config including dev proxy usage and production file replacements.
`frontend/package.json`	Defines Angular dependencies, scripts, and ESLint/Vitest tooling.
`frontend/package-lock.json`	Locks frontend dependency graph for reproducible installs.
`frontend/proxy.conf.json`	Dev proxy to forward `/api/v3` and `/stream` to FastAPI.
`frontend/eslint.config.js`	ESLint flat config with `angular-eslint` rules.
`frontend/.prettierrc`	Prettier config for consistent formatting.
`frontend/.editorconfig`	EditorConfig for consistent whitespace/quotes.
`frontend/.gitignore`	Ignores `node_modules`, build outputs, and tooling caches.
`frontend/README.md`	Documents Angular CLI usage for the new frontend project.
`frontend/tsconfig.json`	Base TypeScript compiler configuration for the Angular project.
`frontend/tsconfig.app.json`	App TS config (excludes specs).
`frontend/tsconfig.spec.json`	Spec TS config (includes `vitest/globals` types).
`frontend/src/main.ts`	Bootstraps the Angular standalone root component.
`frontend/src/index.html`	SPA HTML shell entrypoint.
`frontend/src/styles.scss`	Global SCSS entrypoint.
`frontend/src/environments/environment.ts`	Dev environment config (`apiBase`).
`frontend/src/environments/environment.prod.ts`	Prod environment config (`apiBase`).
`frontend/src/app/app.ts`	Root standalone component definition.
`frontend/src/app/app.html`	Root component template (router outlet only).
`frontend/src/app/app.scss`	Root component SCSS (currently empty).
`frontend/src/app/app.routes.ts`	Router config placeholder (currently empty routes).
`frontend/src/app/app.config.ts`	Application providers / router setup.
`frontend/src/app/app.spec.ts`	Angular unit tests scaffold for the root component.
`frontend/public/favicon.ico`	Frontend favicon asset (used by Angular build).
`.claude/CLAUDE.md`	Updates dev workflow docs for Angular commands and combined dev run.
`ROADMAP.md`	Updates roadmap metadata to mark phases complete / current version.
`docs/plans/2026-03-20-angular-project-scaffold.md`	Detailed implementation plan doc for the Angular scaffold + SPA serving.
`sprints/v3.0.0/README.md`	Adds sprint plan and dependency graph for frontend modernization.
`sprints/v3.0.0/FRONT-001-angular-project-scaffold.md`	Ticket doc for Angular scaffold + SPA serving.
`sprints/v3.0.0/SPIKE-FRONT-001-nodejs-in-distrobox.md`	Spike doc for Node availability in distrobox/host.
`sprints/v3.0.0/SPIKE-FRONT-002-angular-environment-switching.md`	Spike doc for Angular env switching approach.
`sprints/v3.0.0/SPIKE-FRONT-003-dev-server-proxy-verification.md`	Spike doc for proxy verification + dev convenience script.
`sprints/v3.0.0/SPIKE-001-angular-unit-test-setup.md`	Future ticket doc for Angular unit test infrastructure.
`sprints/v3.0.0/SPIKE-002-raw-json-editor.md`	Future ticket doc for raw JSON editor feature.
`sprints/v3.0.0/SPIKE-003-operation-history-view.md`	Future ticket doc for store operation history feature.
`sprints/v3.0.0/SPIKE-004-ci-angular-build.md`	Future ticket doc for adding frontend CI job.
`sprints/v3.0.0/SPIKE-005-starlark-config-ui.md`	Future ticket doc for Starlark UI feature.
`sprints/v3.0.0/FRONT-002-primeng-theme-layout.md`	Future ticket doc for PrimeNG + layout shell.
`sprints/v3.0.0/FRONT-003-api-service-layer.md`	Future ticket doc for typed API/SSE service layer.
`sprints/v3.0.0/FRONT-004-dashboard-module.md`	Future ticket doc for dashboard feature module.
`sprints/v3.0.0/FRONT-005-plugins-module.md`	Future ticket doc for plugins feature module.
`sprints/v3.0.0/FRONT-006-settings-module.md`	Future ticket doc for settings feature module.
`sprints/v3.0.0/FRONT-007-logs-store-modules.md`	Future ticket doc for logs/store feature modules.
`sprints/v3.0.0/FRONT-008-htmx-removal-cleanup.md`	Future ticket doc for removing HTMX legacy UI.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/api/main.py

frontend/src/app/app.spec.ts

test/test_api_spa_mount.py

scripts/dev/run_frontend_dev.sh

src/api/main.py

Olino3 · 2026-03-20T18:19:59Z

@copilot open a new pull request to apply changes based on the comments in this thread

Copilot · 2026-03-20T18:20:07Z

@Olino3 I've opened a new pull request, #34, to work on those changes. Once the pull request is ready, I'll request review from you.

…ts, and dev script Co-authored-by: Olino3 <119822419+Olino3@users.noreply.github.com> Agent-Logs-Url: https://github.com/Olino3/LEDMatrix/sessions/44266a2b-7656-48a9-a014-187d907fb629

olin-3 added 11 commits March 20, 2026 13:04

chore(sprint): mark v1.1.0 and v2.0.0 complete, add v3.0.0 sprint tic…

6dc5e01

…kets Update ROADMAP.md to reflect current version v2.0.0 with Phases 1 and 2 marked complete. Add 13 sprint tickets for Phase 3 frontend modernization (Angular + PrimeNG): 8 core tickets plus 5 SPIKEs.

feat(frontend): scaffold Angular 21 project via ng new

7ec956c

feat(frontend): add dev proxy for API and stream routes

9467c6b

feat(frontend): add environment files with apiBase config

7cdb6b8

test(frontend): add failing tests for FastAPI SPA mount (RED)

f3e52ec

Tests verify Angular SPA catch-all route serves index.html for client-side routing, serves static assets, and does not intercept reserved paths (/api/v3, /docs, /v3, /static).

feat(frontend): wire FastAPI to serve Angular SPA with catch-all route

56eb9fc

chore(sprint): add SPIKE tickets and implementation plan for FRONT-001

306fe49

docs(frontend): document Node.js availability in host and distrobox

53d0117

SPIKE-FRONT-001: Node.js v24 available in both environments via shared NVM. Angular commands run on the host — no distrobox needed. Updated CLAUDE.md with Angular dev commands and workflow.

feat(frontend): wire environment file switching via fileReplacements

bf6b224

SPIKE-FRONT-002: Added fileReplacements to angular.json production config to swap environment.ts with environment.prod.ts at build time. Verified both production and development builds succeed.

feat(frontend): add dev script to run Angular + FastAPI together

c10be9e

SPIKE-FRONT-003: Created scripts/dev/run_frontend_dev.sh and make frontend-dev target. Starts both FastAPI (port 5000) and Angular dev server (port 4200) with proxy forwarding.

chore(sprint): mark FRONT-001 and SPIKE-FRONT-001/002/003 done

68fb717

Copilot AI review requested due to automatic review settings March 20, 2026 18:14

Copilot started reviewing on behalf of Olino3 March 20, 2026 18:15 View session

olin-3 added 2 commits March 20, 2026 14:16

style(frontend): fix import sorting in SPA mount tests

236291f

style(api): format SPA reserved prefixes tuple

063667e

Copilot AI reviewed Mar 20, 2026

View reviewed changes

Copilot AI mentioned this pull request Mar 20, 2026

fix(api+frontend): harden SPA catch-all routing, tests, and dev script cleanup #34

Merged

fix(frontend+api): address all PR review feedback on SPA serving, tes…

34494b0

…ts, and dev script Co-authored-by: Olino3 <119822419+Olino3@users.noreply.github.com> Agent-Logs-Url: https://github.com/Olino3/LEDMatrix/sessions/44266a2b-7656-48a9-a014-187d907fb629

Olino3 merged commit 1c544a8 into develop Mar 20, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(frontend): scaffold Angular 21 project with FastAPI SPA serving#33

feat(frontend): scaffold Angular 21 project with FastAPI SPA serving#33
Olino3 merged 14 commits intodevelopfrom
feature/angular-scaffold

Olino3 commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Olino3 commented Mar 20, 2026

Uh oh!

Copilot AI commented Mar 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Olino3 commented Mar 20, 2026

Summary

Tickets closed

Key decisions

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Olino3 commented Mar 20, 2026

Uh oh!

Copilot AI commented Mar 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants