Architecture: What is the future architecture for distributing shared libr...

Documentation for Sessions

🏗️ Architecture: What is the future architecture for distributing shared libr...

Date: 2026-03-12
Time: 03:11:59 UTC
Session: gspace1-206.7
Agent: angular
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

What is the future architecture for distributing shared libraries to generated platforms (beyond source copy)?

Task: S206: Define future architecture for shared library distribution to generated platforms

🎯 Decision Made

Chosen:

ESM SDK on Cloudflare: Pre-build all shared libs as ESM bundles via ng-packagr, host on Cloudflare R2 (zero egress), serve with Workers for version routing. Generated platforms consume via import maps in index.html — no libs/ directory, no source duplication. AI-ready manifest (manifest.json) documents all 137 libs with capabilities, tier, when-to-use for Vitto's LLM to decide per-platform.

Options Considered:

    1. Keep source copy in every repo (current Phase 1 — works but 1,178 files duplicated)
    1. npm private registry (@gograb/platform-sdk)
    1. ESM SDK on Cloudflare R2 with import maps (chosen for Phase 2)
    1. Git submodules pointing to template repo

💭 Reasoning

Source copy works (proven by 0-error build) but is wasteful: every repo gets 1,178 TS files, 60-80s yarn install, 10-15s build time. npm packages require a publish pipeline and registry. Git submodules are fragile and hard to version. The ESM SDK approach: (1) build once via CI on template changes, (2) upload immutable versioned bundles to R2, (3) generated platforms only contain domain-specific code (~10-20 files), (4) import maps resolve @libs-* to CDN URLs, (5) Angular esbuild respects import maps natively, (6) preview system loads pre-compiled libs instantly. Critical requirement from user: the SDK must be AI-ready — Vitto needs a machine-readable manifest of ALL available libs, not just the base set. The manifest includes tier, exports, description, when-to-use, dependencies. Cloudflare R2 has zero egress fees (unlike S3), Workers handle version routing (/latest/ → /v1.2.0/), edge caching at 300+ locations gives ~5ms worldwide.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation