Skip to content

docs: review pass on remaining docs (principles, reference, examples, guides) - #540

Merged
NhanLuongBGSV merged 2 commits into
eclipse-autowrx:mainfrom
tri2510:docs/remaining-review
Jul 20, 2026
Merged

docs: review pass on remaining docs (principles, reference, examples, guides)#540
NhanLuongBGSV merged 2 commits into
eclipse-autowrx:mainfrom
tri2510:docs/remaining-review

Conversation

@tri2510

@tri2510 tri2510 commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

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), and docs/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-level frontend-dist, a root Dockerfile).
  • 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 both PluginAPI interface blocks (the "complete" one even missed uploadFile), and documented the editable prop.
  • 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).

Factual fixes

  • plugin/02-architecture.md — registration timeout 5s/5015s/150 (matches PluginPageRender.tsx).
  • plugin/README.md, plugin/03-creating-plugin.md — broken PLUGIN_API_POSSIBILITIES.md link → ../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

  • Broken-link target confirmed absent; ComponentRegistry / useMyModels / Banner confirmed absent via grep in frontend/src.
  • Plugin API signatures quoted verbatim from 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.css is at backend/static/global.css; there is no root Dockerfile/docker-compose.yml.

Notes

tri2510 added 2 commits July 17, 2026 14:18
… 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>
@NhanLuongBGSV
NhanLuongBGSV merged commit c601f90 into eclipse-autowrx:main Jul 20, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants