ADR: Initial architecture choices

Date: 2026-01-01

Context

We are rebuilding K-Web and want an architecture that:

• supports independent UI modules
• avoids tight coupling
• supports multiple custom webs from day one
• enables agent-driven development without drifting scope

Decision

• Use Web Components as the UI unit.
• Use CustomEvents as the only cross-component communication channel.
• Keep an internal portable data format, and treat external sources as adapters.
• Prioritize local-first export/import for v1.

Consequences

• Components can be developed and replaced independently.
• Event contracts become a critical piece of documentation and testing.
• The app shell becomes the coordinator; it must stay small and honest.

Alternatives considered

• Framework-based components: rejected for scope and dependency churn.
• Global state library: rejected because events are the core model.
• Server-first storage: deferred until v1 proves the UX.

Follow-ups

• Implement a dev harness (<kweb-inspector>) early.
• Add schema validation for imported web packages.