Note

    ../../DOCS/solution-implementation.md

    Source Summary title: Solution Implementation description: How Hyphenomenon implements its editorial public-experience and living-map strategy via data model...

    Source Summary

    --- title: Solution Implementation description: How Hyphenomenon implements its editorial public-experience and living-map strategy via data models, pipelines, admin workflows, and visualization surfaces status: evolving lastUpdated: 2026-03-20 owner: Product/Engineering --- # Solution Implementation ## Overview Hyphenomenon implements the “living notes + li

    Imported Context

    title: Solution Implementation description: How Hyphenomenon implements its editorial public-experience and living-map strategy via data models, pipelines, admin workflows, and visualization surfaces status: evolving lastUpdated: 2026-03-20 owner: Product/Engineering

    Solution Implementation

    Overview

    Hyphenomenon implements the “living notes + living map” strategy by enforcing one canonical runtime content-and-graph pipeline, then rendering multiple surfaces from that same source of truth.

    That pipeline exists in service of an editorial product: a public-facing system that shows the work, the thinking behind the work, and the connective tissue across projects, methods, and domains.

    At a high level:

    • Canonical public content is loaded from the knowledge backbone repository layer.
    • Canonical public graph data is loaded from the same knowledge backbone and normalized before serving.
    • A single canonical endpoint (GET /api/constellation) serves normalized nodes/edges to every graph surface.
    • Visualization is a unified multi-mode system (DataViz3D) designed to stay maintainable as modes evolve.

    Data Model (What Everything Reduces To)

    Constellation data is expressed as:

    • Nodes: stable id, type, title, summary, url, tags, status, visibility, and optional meta.
    • Edges: source_id, target_id, relation, optional note.

    This model is intentionally simple so it can power:

    • public browsing (SEO-friendly node pages)
    • interactive visualization (3D + 2D audits)
    • admin curation (overrides, hiding, edge lifecycle)
    • machine-readable APIs (/api/constellation, /api/node/:id)

    Source-of-Truth Runtime Pipeline (The “How”)

    1) Canonical Public Content Catalog

    Canonical public catalog records are resolved from the knowledge backbone:

    • loadSiteContentCatalogFromKnowledge in src/lib/server/knowledge/repository.ts
    • exposed through getSiteContentCatalog in src/lib/server/content-catalog.ts
    • returned as projects/notes/domains route-ready catalog shapes

    2) Admin Content Store (Operator State + Audit Layer)

    Admin-managed content (projects, notes, domains) is persisted for operator workflows, lifecycle controls, and audit history via readAdminContentStore/writeAdminState.

    Backends:

    • file (local dev / repo): data/admin-content.json
    • blob (serverless persistence): Vercel Blob objects
    • neon (transactional persistence): Neon/Postgres tables (admin_content_state, admin_history)

    3) Canonical Public Graph (Knowledge Backbone)

    Public graph records are resolved from canonical knowledge data:

    • loader: loadConstellationData in src/lib/server/constellation-data.ts
    • source adapter: loadConstellationFromKnowledge in src/lib/server/knowledge/repository.ts
    • normalization: normalizeConstellationData in src/lib/constellation-normalize.ts

    4) Typed Runtime Hydration

    The canonical repository layer hydrates type-aware metadata onto runtime nodes, including media objects/derivatives and workflow payloads.

    Implementation:

    • src/lib/server/knowledge/repository.ts

    5) Canonical API

    The canonical, normalized runtime graph payload is served by:

    • GET /api/constellation (src/app/api/constellation/route.ts)

    Every graph surface is expected to consume this endpoint rather than maintaining parallel models.

    Product Surfaces (How Users Experience the System)

    Content routes read the canonical public catalog:

    • /projects, /projects/[slug]
    • /notes/*

    Graph routes read the normalized runtime graph:

    • /explore
    • /admin (Information Architecture (Full))
    • /node/[id] detail flows

    Together, these surfaces are meant to function as more than a documentation shell:

    • a public editorial body of work
    • a map of how the work relates
    • a credibility surface for consulting, collaboration, and domain expertise in AI-assisted and systems-oriented work

    Visualization Implementation (Multi-Mode, Maintainable)

    Visualization is implemented as a unified system:

    • Orchestration: src/components/diagrams/DataViz3D.tsx
    • Engine hook (Three.js lifecycle + interaction): src/hooks/useDataViz3DEngine.ts
    • Overlay UI: src/components/diagrams/DataViz3DOverlay.tsx
    • Pure layout/simulation helpers: src/lib/dataviz3d/layout.ts

    Modes:

    • Constellation (default; editorial, calm, spatially legible)
    • Venn Diagram
    • Mind Map

    The visualization layer should support curiosity, narrative coherence, and trust, not just information density.

    Admin-managed tuning:

    • Stored in store.meta.visualizer_config
    • Served via GET /api/visualizer-config (see DOCS/development/admin-content-architecture.md)

    Admin Implementation (Curation + Auditability)

    Admin route:

    • /admin

    Key behaviors:

    • server-side validation on PUT /api/admin/data (path-level errors)
    • lifecycle semantics (active/removed + removed_at, plus optional permanent delete)
    • edge lifecycle removals (overrides.removed_edges) to support remove/restore semantics without losing history
    • audit history capture (admin vs external changes), with snapshot hashing for drift detection

    These private operator tools exist to maintain public editorial quality and canonical integrity, not to turn the product into a productivity dashboard.

    See:

    • DOCS/features/admin-panel.md
    • DOCS/development/admin-content-architecture.md

    Operations (Keeping Truth Canonical Over Time)

    Operational scripts exist to ensure the “single source of truth” stays true in production:

    • post-deploy parity checks: npm run ops:parity:postdeploy
    • Neon backup/restore drill: npm run ops:neon:backup-restore-drill
    • blob fallback verification: npm run ops:blob:fallback-verify
    • release gate runner: npm run ops:release-gate

    See: scripts/ops/README.md

    Docs System (Keeping the Map Accurate)

    Documentation source of truth is DOCS/:

    • VitePress site build lives under docs-site, output DOCS/.vitepress/dist
    • Docs tooling:
      • manifest generation: npm run docs:manifest (writes DOCS/manifest.json)
      • link checking: npm run docs:links
      • frontmatter normalization: npm run docs:frontmatter

    Related Docs

    • DOCS/strategist-logic.md
    • DOCS/project-master.md
    • DOCS/development/tech-stack-information-architecture.md
    • DOCS/development/dataviz-architecture.md
    • DOCS/features/constellation-visualization.md
    • DOCS/features/information-architecture-map.md
    • DOCS/features/admin-panel.md

    Provenance