Architecture

This doc describes boundaries, data flow, and how components are wired.

High level

K-Web is a client-heavy app. The server’s default job is:

• serve static assets
• optionally persist and fetch webs (files, DB, or both)
• optionally provide auth later

The UI is made of Web Components:

• <kweb-app> (app shell)
• <kweb-graph>
• <kweb-timeline>
• <kweb-map>
• <kweb-bio>
• <kweb-search>
• <kweb-trails>
• <kweb-editor> (node/link editing)
• <kweb-web-picker>
• optional <kweb-spheres>
• <kweb-inspector> (dev harness, optional)

Event-first wiring

All cross-component communication happens via CustomEvents. See ./event-contracts.md.

Rules:

• Components listen for events on themselves or a shared root element provided by <kweb-app>.
• Components emit events with JSON-serializable detail.
• No direct references to sibling components.

App shell responsibilities

<kweb-app> owns:

• Routing
  • URL → selection state
  • selection state → URL
• Web loading
  • pick web
  • load/save/export/import
• Data distribution
  • provide the current web snapshot to components (as data, not as services)
• Coordination
  • translate “preview” vs “commit” into consistent view updates
• Feature flags
  • spheres on/off
  • inspector on/off
  • mock data mode

State model

We separate three related states:

• Hover state (preview)
• Selection state (committed)
• View state (per view, e.g., graph zoom, map camera, timeline zoom)

A practical approach:

• App shell keeps a single “interaction state” object:
  • selectedNodeId
  • hoverNodeId
  • timeRange (optional)
  • activeWebId
• Views maintain their own internal UI state (camera, zoom), but should be able to serialize it when asked.

Data adapters

The internal format is defined in ./data-model.md.

Adapters are optional modules that translate external sources into the internal format:

• The Brain export adapter (future)
• Old XML adapter (future)
• Wikipedia/Wikidata enrichment adapter (future)

Adapters must not leak into core component logic. Core components only know the internal format.

Server notes

Node server can be Express initially.

Minimum server endpoints (optional for v1 if local-only):

• GET /api/webs list webs
• GET /api/webs/:id fetch web
• POST /api/webs/:id save web
• POST /api/import import web
• GET /api/export/:id export web

A v1 alternative is local-only storage (IndexedDB / local file export) and the server only serves the app.

Security and trust boundaries

• Treat imported web files as untrusted input.
• Sanitize any HTML in Bio content, or store as a safe rich-text format.
• Never execute code from content.

Definition of done (architecture)

• [ ] Every cross-module interaction is an event contract.
• [ ] App shell is the only place that “knows everyone”.
• [ ] A view can be removed without breaking others (graceful degradation).