docs(architecture): configuration-over-code page + atom-card page-types#328
docs(architecture): configuration-over-code page + atom-card page-types#328rubenvdlinde wants to merge 3 commits into
Conversation
…-types - New /docs/architecture/configuration-over-code page framing the manifest + schemas contract as the safe sandbox for AI agents and citizen developers. Links to the academy tutorial on spec-driven development and to conduction.nl/apps/openbuilt. - Manifest page: "Page types" section restructured from a flat table into atom-aware cards (one per type), matching the AtomZones vocabulary used on the app-design-principles page. Each card shows the atom composition (present/off) plus what fills Main and what the Sidebar carries. - Sidebar positions bumped: schemas-and-registers 3 -> 4, customization 4 -> 5, to make room for the new page at position 3. - Landing page: 5th entry-point tile "Configuration over code" added, eyebrow text updated from "Four entry points" to "Five entry points".
- overview.md: replace the Mermaid 3-layer graph with three stacked cn-domain-tree hex diagrams (Your app / @conduction/nextcloud-vue / @nextcloud/vue), middle trunk in orange to mark the layer this site documents. Side-effect import of @conduction/docusaurus-preset/diagrams, wrapped in BrowserOnly for SSR safety. - configuration-over-code.md: rewrite the "Spec-driven development" section around OpenSpec (the real Hydra method): humans write specs + ADRs, AI implements to them; org-wide vs per-app ADR tiers; the /opsx-explore and /opsx-apply skills; ADR-031 declarative business logic with n8n/Windmill via WorkflowEngineInterface; the quality + gatekeeping harness. Was incorrectly framed as the JSON-manifest authoring workflow.
The top-level `import '@conduction/docusaurus-preset/diagrams'` defined web-component classes extending HTMLElement at module-eval during static site generation, where HTMLElement is undefined. Drop the top-level import; require() the diagrams module inside the BrowserOnly render function so it only runs in the browser.
|
Superseded by #331, which targets |
| # Configuration over code | ||
|
|
||
| The point of `@conduction/nextcloud-vue` + OpenRegister isn't "less Vue to write". It's **less code, full stop**. Every page, every form, every list, every dashboard tile that a Conduction app ships is meant to be a row in a JSON file, not a `.vue` file in a `src/` tree. | ||
|
|
There was a problem hiding this comment.
🟡 configuration-over-code.md is placed at sidebar_position: 3 — collides with schemas-and-registers.md before its position bump
configuration-over-code.md sets sidebar_position: 3. The PR also bumps schemas-and-registers.md from 3 → 4 and customization.md from 4 → 5, so the final order is 1 (overview), 2 (manifest), 3 (config-over-code), 4 (schemas-and-registers), 5 (customization). Within a single commit/build this is fine because both files are applied together — but the positional intent should be documented here. No action needed; just confirming it is consistent.
|
|
||
| The end state of the configuration-over-code shift is that you don't author either file by hand. **OpenBuilt** is the visual app builder we're building on top of the manifest contract: drag schemas in, point and click the navigation, preview the chassis, publish — no JSON editor, no terminal, no Vue, no review. | ||
|
|
||
| → [OpenBuilt — visual app builder](https://conduction.nl/apps/openbuilt) |
There was a problem hiding this comment.
🟡 External links in configuration-over-code.md are not verified to be live
Two external URLs are introduced:
https://conduction.nl/academy/spec-driven-development(referenced twice)https://conduction.nl/apps/openbuilt
Neither could be verified as live at review time. If these pages do not yet exist, readers will hit 404s. Consider linking to a coming soon anchor or using a placeholder note until the URLs are live.
WilcoLouwerse
left a comment
WilcoLouwerse
left a comment
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES — two blockers: (1) branch-protection / check-branch is REQUIRED and failing (same pattern as #236 — source branch name likely doesn't satisfy the convention); (2) unescaped apostrophes (library's, platform's) inside a single-quoted JS string in docusaurus/src/pages/index.js:297 terminate the string literal early and will break the Docusaurus build. Fix: switch to double quotes or a template literal. All internal docs cross-links resolve and MDX/JSX safety is otherwise correct.
Inline comments:
- 🟡
configuration-over-code.mdis placed atsidebar_position: 3— collides withschemas-and-registers.mdbefore its position bump - 🟡 External links in
configuration-over-code.mdare not verified to be live
Additional findings:
🔴 Required CI check failing: branch-protection / check-branch
The branch-protection / check-branch required check is failing, which blocks merging. This is the same pattern seen on other PRs targeting beta — the branch name (docs/config-over-code-and-atom-cards) likely does not satisfy the branch-naming convention enforced by the check. The PR author should confirm the target branch is correct or rename the source branch to match the convention. No code change in this PR can fix a branch-naming gate.
🟢 All internal cross-links resolve on beta
All internal doc links introduced in the PR were verified against the beta branch tree:
./manifest.md✓./schemas-and-registers.md✓./app-design-principles.md✓ (exists onbeta)/docs/utilities/composables/use-app-manifest✓- All eight
CnXxxPagecomponent links (/docs/components/cn-*-page) ✓
🟢 MDX safety in manifest.md — inline style props are valid JSX
The new atom-card grid in manifest.md uses <div style={{ ... }}> JSX-style inline styles with double-brace syntax, which is correct for MDX. No unescaped { characters, no raw HTML attributes that would be rejected by the MDX parser. The @docusaurus/BrowserOnly usage in overview.md is also correct: the custom-element tags (<cn-domain-tree>, <cn-hex>) are wrapped inside BrowserOnly to avoid SSR issues with non-registered web components.
🟢 JSDoc ratchet failure in Code Quality is pre-existing and unrelated to this PR
The Frontend Quality / JSDoc completeness ratchet step has been failing consistently on all recent beta PRs (at least 5 consecutive SHAs before this one). It is a repo-wide pre-existing issue not introduced by this docs-only change and should not block this PR independently.
🟡 Unescaped apostrophes break JS string literal in index.js
The new CARDS entry in docusaurus/src/pages/index.js uses a single-quoted string for body, but the value contains two bare apostrophes: library's and platform's. These terminate the string literal early, causing a JavaScript syntax/parse error that will break the Docusaurus build.
Fix: either escape the apostrophes (library\'s, platform\'s) or switch the string delimiter to a template literal or double quotes:
body:
"Every page, form, list, and dashboard is a row in a JSON file — not a .vue file. That makes the same contract safe for AI agents and citizen developers to author, because the runtime stays the library's and the sandbox stays the platform's.",(intended for docusaurus/src/pages/index.js:297)
2 participants
Summary
/docs/architecture/configuration-over-code/— frames the manifest + schemas contract as the safe sandbox for AI agents and citizen developers. Names the failure modes that the JSON contract collapses (typo → validation error, no JS to execute, bounded blast radius, reversible changes), and links to:conduction.nl/academy/spec-driven-development(companion PR on ConductionNL/conduction-website)conduction.nl/apps/openbuilt(visual app builder; same contract, no JSON editor)Test plan
cd docusaurus && npm start— landing page shows five cards in the grid, no MDX/JSX parse errors on the manifest page./docs/architecture/manifest/→ "Page types" renders as eight cards with atom rows./docs/architecture/configuration-over-code/resolves; outbound links render.npm run check:docsstill passes.