Skip to content

docs: rewrite README to match codebase and range42 org conventions #56

@t0kubetsu

Description

@t0kubetsu

Summary

The current README has significant gaps and structural issues compared to other range42 repos and the actual codebase state.

Problems identified

Structural (org convention violations)

  • Opens with # Table of Contents as H1 instead of the repo slug — breaks Pattern A used by all strong range42 repos
  • Missing "Part of the range42 platform" anchor link in the opener
  • Contains copy-paste boilerplate ("What we build" / "Repository Overview") shared verbatim with range42-catalog and range42-api-definitions
  • No architecture diagram showing the UI → backend-api → Ansible → Proxmox chain
  • No inter-repo cross-links to range42-backend-api or range42-playbooks

Stale / inaccurate claims

  • "Future versions will integrate SQLite WASM" — @sqlite.org/sqlite-wasm is already a production dependency with an active config at src/config/database.js
  • "either from the UI (coming soon)" — UI-based deployment is fully implemented (useDeployment.ts, deploymentStore.ts, DeploymentPanel.vue)
  • Data storage described as only localStorage — per-project backend settings are stored in browser cookies (range42.settings.<projectId>)
  • i18n section lists only en and fr — Japanese (jp) is also fully supported

Missing features (implemented in code, absent from README)

  • Infrastructure import from live Proxmox (VMs + LXC with real-time status)
  • Template & ISO browser (storage pool browsing, ISO download by URL)
  • Git-backed inventory system (multi-repo, read/write via GitHub API, scenario loading)
  • Full deployment engine controls: pause, cancel, resume, retry, skip steps
  • VM lifecycle management per role: start, stop, pause, resume, snapshot, revert, delete
  • Real-time Proxmox polling (useProxmoxStatus.ts, 5s interval)
  • Project management dashboard (search, grid/list toggle, node stats, duplication)
  • Settings view (/settings route: theme, snap-to-grid, storage stats)
  • Tech stack not listed anywhere

Fix

  • Rewrite README following range42 Pattern A conventions
  • Add ASCII architecture diagram
  • Add tech stack table
  • Add project structure tree
  • Document all implemented features accurately
  • Correct all stale claims
  • Add prerequisites and backend connection instructions
  • Condense i18n section and link to docs/i18n-guide.md

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions