docs: add frontend architecture and services contract references - #6
Merged
Conversation
A new app built from this starter should not have to rederive the directory layout or the backend wiring pattern. Both are documented here, grounded in what this repository actually contains. frontend-architecture.md covers the src/ skeleton: the components/ vs features/ split, layouts, lib/ vs utils/, where state belongs, and the routing layers. It marks explicitly which parts this starter ships and which are the shape a full app grows into, so nothing reads as a claim about code that is not here. frontend-services-contract.md covers the contract-to-hook chain for an app that adds a backend: what codegen owns versus what you write by hand, the four hook conventions, and how errors should be normalised. This starter has no api/, models/, services/ or hooks/ yet, and the document says so. Also replaces the References TODO block in frontend-conventions.md, which listed four references that did not exist. Three now do; validation is dropped as a separate entry because the Validation section above it already carries this repo's exact commands. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Gives a new app built from this starter the two things it would otherwise have to rederive: where code goes, and how a backend endpoint is wired.
Why here
These were briefly published in
pathscale/uiand removed again (pathscale/ui#200) — that version described private application repositories in a public repo. This starter is the right home: it's public, and it's already the thing new apps begin from.Rewritten from scratch against this repository. No private repository is named, and no path from one is cited.
The two docs
frontend-architecture.md— thesrc/skeleton. Thecomponents/vsfeatures/split (with the one-way import rule), layouts,lib/vsutils/,stores/vscontexts/, the three routing layers, and a "where does this go?" table.frontend-services-contract.md— the contract-to-hook chain: what codegen owns versus what you write, the four hook conventions, and four rules for error normalisation (chief among them: never branch on a message string).Honest about what's here
This starter ships part of the skeleton and none of the data layer. Rather than describe directories that don't exist, both docs mark each section as either in this starter or the shape a full app grows into. The services doc says outright that there is no
api/,models/,services/orhooks/here yet and that it describes a target.That also makes the gap visible: if you'd like the starter to ship that scaffolding rather than just document it, that's a natural follow-up and I'd suggest it.
Also
Replaces the References TODO block in
frontend-conventions.md, which listed four references that didn't exist. Three now do.validationis dropped as a separate entry — the Validation section directly above it already has this repo's exact commands, so a reference entry would only drift from it.Verification
Every
src/path cited was checked against this repository. Scanned both new files for private repository names: zero.🤖 Generated with Claude Code