docs(app): add frontend ARCHITECTURE.md and refresh project-guide section#8596
Conversation
…tion - app/ARCHITECTURE.md: directory layout, conventions (src/ alias, paths registry, lib/api client, theme tokens), data flow, testing pattern, quality gates, and how-to-add recipes - project-guide.md frontend section now lists the full gate (lint, fm:check, type-check incl. tests, test) and links the new architecture doc Part 11 of the frontend modernization roadmap. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
Adds/refreshes frontend documentation to close out the “frontend modernization roadmap” by documenting the current app structure, conventions, and the local/CI quality gates.
Changes:
- Add
app/ARCHITECTURE.mddescribing frontend directory layout, conventions, data flow, testing approach, and “how to add” recipes. - Update
agentic/docs/project-guide.mdfrontend section to reflect the current gate commands and link to the new architecture doc.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| app/ARCHITECTURE.md | New frontend architecture/conventions doc; needs a few wording corrections to match current code/CI behavior. |
| agentic/docs/project-guide.md | Updates frontend dev guidance (lint/format/type-check/tests) and links to the architecture doc. |
| - **Imports** are absolute from the `src/` alias (`import { paths } from 'src/routes/paths'`); | ||
| no relative `../` imports. ESLint (perfectionist) enforces sorted, grouped imports. |
There was a problem hiding this comment.
Applied — reworded to 'no relative imports between src/ modules' with the package.json exception called out.
| CI (`.github/workflows/ci-tests.yml`, job `test-frontend`) runs the same gates; | ||
| `yarn type-check` covers app and test files (`tsconfig.test.json`). During | ||
| development, `vite-plugin-checker` surfaces TS/ESLint errors in the browser. |
There was a problem hiding this comment.
Applied — the doc now states CI runs lint/format/type-check/tests while yarn build runs in the Cloud Build Docker build on merge.
| - **API access** goes through `src/lib/api` (`apiGet`/`apiPost` + `endpoints`); | ||
| raw `fetch()` lives only inside that module. Callers own caching/abort/dedup. |
There was a problem hiding this comment.
Applied — scoped the rule to the anyplot backend and documented the external-API exception (useLatestRelease).
| - **URLs** never appear as string literals in components — use `paths.*` from | ||
| `src/routes/paths` (static routes, `paths.plotsFiltered(param, value)`, | ||
| `paths.spec(specId, language, library)`). |
There was a problem hiding this comment.
Applied in code rather than softening the doc — MastheadRule breadcrumbs, the routes redirect, and SpecPage pageview tracking now use specPath; no route string literals remain in components.
…pen docs Copilot review findings on the architecture doc — three doc/reality gaps closed by precision wording (src-internal import rule, lib/api scope incl. the external GitHub-API exception, CI-vs-Cloud-Build gate split) and one by code: MastheadRule breadcrumbs, the routes redirect, and SpecPage pageview tracking now build spec URLs via specPath instead of template literals. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Summary
Part 11 (final) of the frontend modernization roadmap.
app/ARCHITECTURE.md: directory layout (routes/layouts/pages/sections/components/hooks/lib/theme), conventions (src/alias imports,paths.*URL registry,lib/apiclient, theme tokens, feature folders), data flow, testing pattern, quality gates, and how-to-add recipes for pages/sections/hooks/endpointsagentic/docs/project-guide.md: frontend section now lists the full gate (lint,fm:check,type-checkincl. tests,test), mentions the dev-time checker overlay, and links the new architecture docWith this, the roadmap is complete: tooling baseline (#8519), src/ aliases (#8520), theme split (#8525), global-config (#8529), API client (#8531), routes registry (#8546), structure split (#8547), FilterBar (#8559), SpecTabs (#8564), MapPage hook (#8581).
🤖 Generated with Claude Code