docs: review pass on remaining docs (principles, reference, examples, guides) - #540
Merged
NhanLuongBGSV merged 2 commits intoJul 20, 2026
Merged
Conversation
… guides) Code-verified the docs outside getting-started/ and architecture/ and corrected factual errors, plus flagged outdated/aspirational pages. Factual fixes: - plugin/02-architecture.md: registration timeout 5s/50 -> 15s/150 (matches PluginPageRender REGISTER_TIMEOUT_MS=15000, POLL_INTERVAL_MS=100). - plugin/README.md, plugin/03-creating-plugin.md: fix broken PLUGIN_API_POSSIBILITIES.md reference -> ../plugin-api-possibilities.md. - plugin/04-api-reference.md: the API is larger than the documented "14 methods" (also includes asset + kit/runtime operations); note that the page is incomplete. - reference/feature-breakdown.md: correct outdated builtin routes (/user/asset -> /my-assets, /admin/manage-user -> /admin/manage-users, /models/:mid... -> /model/:model_id/library/prototype/:prototype_id). Outdated/aspirational notices (flagged, not rewritten): - principles/project-structure.md: describes an old v1 layout. - reference/csp.md: shipped CSP is wildcard-permissive, not the tight policy documented here (target only). - reference/component-design/dynamic-components.md + docs/examples/*: the "Dynamic Component Architecture" (ComponentRegistry) is not implemented; the examples are conceptual. - guides/plugin-api-possibilities.md: several "future" items are already implemented. Documentation only; no code changed. Signed-off-by: Tri Hua <tri2510@gmail.com>
…s to real code
Follow-ups folded into this PR per review:
- principles/project-structure.md: full rewrite to the current layout
(backend/src/routes/v2/{user-management,vehicle-data,content,system},
backend/src/index.js, backend/static/frontend-dist/, backend/Dockerfile,
instance-setup/). Drops the old v1 layout and the temporary "outdated"
banner.
- guides/plugin/04-api-reference.md: complete the API reference. The
Plugin API has 28 methods across 8 categories (not 14). Added Asset
Operations (8) and Kit/Runtime Operations (4) sections, fixed both
PluginAPI interface blocks (the "complete" one even missed uploadFile),
and documented the `editable` prop on PluginPageProps.
- reference/component-design/dynamic-components.md + docs/examples/*
(5 files): replaced the fictional "Dynamic Component Architecture"
(ComponentRegistry / renderComponentByTypeName) and fictional examples
(Banner, ModelsGrid, useMyModels, ...) with the real implementation —
PageHome's config + getComponent switch, route-level React.lazy +
retry(), and real components/hooks/pages (HomeHeroSection, DaModelItem,
useCurrentModel, PageModelList). Drops the temporary banners.
Documentation only; no code changed.
Signed-off-by: Tri Hua <tri2510@gmail.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
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.
Summary
Code-verification pass over the remaining
docs/areas not covered by #538 (getting-started) or #539 (architecture):principles/,reference/,examples/,guides/(incl. the plugin guide), anddocs/README.md.Headline finding: unlike the architecture docs (~95% accurate), several "remaining" docs were significantly outdated or fictional. This PR corrects the factual errors and rewrites the worst offenders to match the current code. No code changed — documentation only.
Rewrites (to the current code)
principles/project-structure.md— full rewrite to the real layout (backend/src/routes/v2/{user-management,vehicle-data,content,system},backend/src/index.js,backend/static/frontend-dist/,backend/Dockerfile,instance-setup/). The old doc described a v1 layout (routes/api/*-management, a top-levelfrontend-dist, a rootDockerfile).guides/plugin/04-api-reference.md— completed. The Plugin API has 28 methods across 8 categories (not 14). Added Asset Operations (8) and Kit/Runtime Operations (4) sections, fixed bothPluginAPIinterface blocks (the "complete" one even misseduploadFile), and documented theeditableprop.reference/component-design/dynamic-components.md+docs/examples/*(5 files) — replaced the fictional "Dynamic Component Architecture" (ComponentRegistry/renderComponentByTypeName) and fictional examples (Banner,ModelsGrid,useMyModels, …) with the real implementation:PageHome's config +getComponentswitch, route-levelReact.lazy+retry(), and real components/hooks/pages (HomeHeroSection,DaModelItem,useCurrentModel,PageModelList).Factual fixes
plugin/02-architecture.md— registration timeout5s/50→15s/150(matchesPluginPageRender.tsx).plugin/README.md,plugin/03-creating-plugin.md— brokenPLUGIN_API_POSSIBILITIES.mdlink →../plugin-api-possibilities.md.reference/feature-breakdown.md— corrected stale builtin routes (/user/asset→/my-assets,/admin/manage-user→/admin/manage-users,/models/:mid/prototypes/:pid→/model/:model_id/library/prototype/:prototype_id).Noted, not changed (would touch code or need a decision)
reference/csp.md— the shipped CSP (app.js) is wildcard-permissive, not the tight policy documented here; the doc now says so. Tightening the shipped CSP is a code/product change, kept out of this docs PR.guides/plugin-api-possibilities.md— several capabilities listed as "future" are already implemented; noted inline.Verification
ComponentRegistry/useMyModels/Bannerconfirmed absent viagrepinfrontend/src.frontend/src/types/plugin.types.ts; example code quoted from the real files (PageHome.tsx,useCurrentModel.ts,DaModelItem.tsx,HomeHeroSection.tsx,configs/routes.tsx).global.cssis atbackend/static/global.css; there is no rootDockerfile/docker-compose.yml.Notes
Tri Hua <tri2510@gmail.com>).main; does not depend on getting-started onboarding: docs + local-dev config + unblock backend tests (new-user review) #538 or docs(architecture): code-verify fixes (counts, rate-limit, token lifetime, startup, toJSON) #539.