xyz-platform-context
High-level domain documentation for XYZ Reality's HoloConstruct platform.
Aimed at developers joining the project and AI copilots that need architectural context to make informed code changes.
Conventions
| Guideline | Why |
|---|
| Keep files concise — explain the "what" and "why", link out for deep details | Avoids stale duplicates of implementation docs |
| Note pitfalls and gotchas explicitly | Saves hours of debugging |
| Include goals and planned work | Gives direction even when Jira is unavailable |
| Use plain language over code | This isn't API reference; it's conceptual grounding |
Domains
| Domain | Path | Description |
|---|
| Dashboard Page | dashboard/ | In-browser analytics + 3D viewer replacing PowerBI |
| Canvas Page | canvas/ | AI chat interface — natural-language → streaming TSX dashboards |
| Agent Pipeline | agent-pipeline/ | FastAPI backend for the Canvas: phases, SSE, MCP tools, caching |
| Commissioning | commissioning/ | Flag-gated MVP: asset register, checklists, 3D linking, handover readiness — on a temporary Supabase bridge |
Add new domains as folders here. Each domain gets a README.md and topic files.
Running tests
hc-frontend's suite cannot be installed with the tokens a cloud agent session
has — npm ci 401s on the private @xyzreality/dhtmlx-gantt. There is a working
stub-and-install round it in
running-tests-in-agent-sessions.md.
Read it before deferring any work with "can't run the tests here".
Planning
Cross-cutting ticket plans live in planning/. One file per ticket, named PLT-XXXX-slug.md.
Domain-specific plans live alongside their domain (e.g. canvas/planning/, agent-pipeline/planning/).
Relationship to docs/
The existing docs/ folder contains deep technical references (DuckDB schemas, API mappings, Mermaid diagrams).
This folder is the entry point — read here first, then follow links into docs/ when you need implementation specifics.
XYZ_AgentPipeline/docs/ has been consolidated here — all pipeline design docs and plans are now under agent-pipeline/ and canvas/.
