S187 Roadmap Note — Nuxt Laws Page Tree View, Auto Numbering, Review Overlay, and Reorder Architecture after P10A-2C

Date: 2026-04-29

User direction

The existing route/tab:

https://vps.incomexsaigoncorp.vn/knowledge/laws

was created under an older design. It may be replaced/reworked. The route and homepage tab should be reused, but the page design should be rebuilt around the new PostgreSQL/TAC information-unit architecture.

Product vision

The KB becomes a draft/reference layer. For a transition period, the old human-readable KB document and the new PG-assembled document may coexist.

The /knowledge/laws page should become the place where users can see documents reassembled from PG units, not from monolithic KB markdown.

The page should show:

1. A tree view of documents and their parent-child structure.
2. A way to click a document/file/node and read the reconstructed human-readable document.
3. The correct order of units inside each document.
4. The parent-child structure of sections/units, not just flat ordering.

In future, this page can become the only official reading channel once the system matures.

New roadmap requirement — auto numbering and reorder

User added an important practical requirement:

• For automatic arrangement, information units must have an automatic numbering / ordering mechanism.
• In real work, users/agents may insert a new unit in the middle, split an existing unit, merge units, or move units across parent-child positions.
• When this happens, display numbers and ordering must update automatically.
• The tree view must reflect both:
  1. parent-child relationship; and
  2. sibling ordering inside each parent.
• The system must preserve stable internal IDs while allowing human-facing numbers/order labels to be regenerated.

This requirement should be treated as part of future render/tree architecture, not a P10A-2C blocker.

New roadmap requirement — optional unit boundary overlay

User confirmed a practical review need:

• Normal readers need a clean document view.
• Authorized administrators/reviewers need a toggle button to turn on a subtle visual layer showing information-unit boundaries.
• When the layer is OFF, the document looks clean and familiar.
• When the layer is ON, the page shows soft boundaries so reviewers can see which text belongs to which unit.
• Access to this overlay must be controlled through admin/permissions.

This should be implemented as a view layer, not by changing the stored document content.

View modes to design

Future /knowledge/laws should support at least:

1. Reader Mode — default clean document view. No unit boundaries visible.
2. Review Mode — admin-authorized toggle shows subtle information-unit boundaries.
3. Debug Mode — deeper technical metadata for operators, if separately authorized.

Review Mode examples:

• faint left border per unit;
• subtle background bands;
• margin badges with unit key/section type;
• hover/click to show unit metadata;
• tree node highlights when clicking a text unit;
• no disruption to normal reading flow.

Admin/permission requirement:

• only authorized roles can see or toggle Review Mode;
• default public/normal user view remains Reader Mode;
• permission model should align with Directus/TAC roles later.

Design implications

Future design must distinguish at least three concepts:

1. Stable identity — internal UUID/entity/unit key that must not change when order changes.
2. Structural position — parent_id + ordering key/path used by PG/render/tree traversal.
3. Human-facing numbering — display number such as 1, 1.1, 1.2, a/b/c, §4.1, etc.; this may be regenerated after insert/split/merge.

Do not rely on fixed hardcoded numbering as the source of truth.

Review overlay is a fourth presentation concept:

4. Visible review boundary — optional UI-only layer that exposes unit spans without changing stored content.

Future capabilities to design

The future gate must support:

• automatic sibling ordering;
• insertion between two existing units;
• splitting one unit into several child/sibling units;
• merging multiple units;
• moving a unit to another parent;
• renumbering display labels without changing stable IDs;
• maintaining deterministic tree preorder;
• recording reorder/split/merge history for audit;
• rendering updated numbering correctly in /knowledge/laws;
• optional unit-boundary overlay controlled by permissions.

Potential technical approaches to evaluate later:

• fractional/decimal sort keys;
• materialized path ordering;
• generated display numbers from tree traversal;
• separate relation table for typed parent-child and ordering relations;
• order repair/rebalance function;
• audit log for reorder operations;
• UI overlay layer for unit boundaries;
• role/permission gate for review/debug modes.

No approach is selected yet.

Sequencing decision

Do not merge this into P10A-2C.

P10A-2C must first produce a clean reconstructed markdown document from PG for one publication. That becomes the sample/proof for the Nuxt page.

After P10A-2C PASS, create a separate design/implementation gate:

P10D / Nuxt Laws Page Tree View + Reader/Review Modes + Auto Numbering Design

or equivalent name.

Why after P10A-2C

P10A-2C verifies the core render logic without frontend complexity:

• PG units can be read in tree order;
• synthetic root/placeholders can be hidden;
• a familiar document can be reconstructed;
• diff/readability can be verified.

Only after this works should the Nuxt page consume the same logic.

Initial technical scope for future gate

Minimum product slice:

• reuse existing route /knowledge/laws;
• reuse or redesign homepage tab;
• page layout with left tree view and right document reader;
• tree sourced from PG TAC publication/logical_unit/member structure;
• click document/node to read reconstructed human-readable content;
• read-only UI first;
• Reader Mode default;
• Review Mode toggle for authorized admins/reviewers;
• optional subtle unit boundary overlay;
• tree displays parent-child structure and correct sibling order;
• later: automatic display numbering/re-numbering after insert/split/merge;
• no editing, approval, migration, KG/vector, or lifecycle changes in first slice unless separately gated;
• old KB content may remain accessible as reference/draft during transition.

Architecture note

This is part of Pivot-based rendering: documents are assembled from information units according to a chosen pivot/view. Initial pivot = document/file order. Future pivots may include topic, process, role, system, or relationship graph.

The auto-numbering requirement is also part of Pivot rendering: the same stable unit graph may have multiple human-facing order/number projections depending on the selected pivot.

The review overlay requirement is a presentation layer on top of the same unit graph. It must not alter source content or canonical PG records.

Status

Roadmap note updated. Execute after P10A-2C clean render, not inside P10A-2C.