ADRs
Overview

Architecture Decision Records для ARNO проекта.

Назначение

ADR — формальный артефакт major architectural decisions. Каждый ADR fixates:

  • Context — почему решение нужно сейчас
  • Decision — что выбрали
  • Consequences — последствия (плюсы, минусы, trade-offs)
  • Alternatives — что отвергли и почему

Per Rules.md §governance: major architecture changes требуют ADR перед изменением master spec.

Когда создавать ADR

Triggers:

  • Vendor migration (Liveblocks → self-hosted Yjs, Cloudflare → AWS, etc.)
  • Replace core dependency (Auth.js → Lucia, react-flow → alternative)
  • Switch backend/frontend runtime
  • Microservice extraction из monolith
  • Major schema redesign
  • Crypto algorithm changes (§0.5)
  • New architectural principle добавить в §0.3

NOT triggers (minor):

  • Refactoring within module
  • Library version bumps
  • Bug fixes
  • New endpoints в existing API contract

Naming convention

NNNN-short-title-lowercase.md где NNNN — 4-digit sequential (0001-, 0002-, ...).

Template

См. README.md — full ADR template + process.

Active ADRs

{/* AUTOGEN:adr-index START */}

Auto-generated by scripts/gen-adr-index.ts on 2026-09-08. Do not edit by hand — regenerate via pnpm docs:adr-index.

Core ARNO

#TitleStatusDatePhase / Feature
0001Static export now, edge adapter when Auth/API landAccepted2026-05-200 → 8
0002Module-level stores + useSyncExternalStoreAccepted2026-05-202 → 7
0003Design-system source: local snapshot → GitHub APIAccepted (replaces interim local snapshot)2026-05-205
0004Render adapter postMessage protocolAccepted (v1)2026-05-206 → 7
0005Dedicated Worker для API, не Pages FunctionsAccepted2026-05-218
0006Backend-driven GitHub OAuth, не Auth.js на PagesAccepted2026-05-219
0021Scale target: 30K MAU as design ceilingAccepted2026-05-25—
0022Environments + branching model (trunk-based, ephemeral previews)Accepted (v2.0). Supersedes the v1.0 env-branch model below.2026-05-25 (v1.0) · 2026-05-29 (v2.0 — supersedes v1.0)—
0023Deploy pipeline (project → connected repo)Accepted2026-05-26—
0024Storybook design system catalog (replaces design-system.html)Accepted2026-05-26—
0027Composition zones unification + deploy mutexAccepted2026-05-27—
0028Deploy JSON consumerResolved — decision is to defer. Not pending work. The ADR 0027 open question ("who reads pages/{id}.layout.json?") is answered: no consumer is built until a user demands a public render URL. Today the artifact is audit-and-restore only. This is a deliberate, final decision per YAGNI — re-open only when a trigger below fires.2026-05-27—
0029Auto-apply migrations в CI для solo-dev workflowAccepted (deviation от master spec §III.2.5; revisit when team > 1)2026-05-27—
0030Page reconstruction: decompose capture → distribute → reassembleAccepted (B1–B6 implemented; commercial-gate Tranco lookup deferred)2026-05-28—
0031Workflow tab redesign: unified Figma-style canvasProposed (awaiting implementation kickoff)2026-05-31—
0032Reassembly rendering: iframe+bridge now, Shadow DOM laterProposed2026-06-03—
0033Extension crawl-mode: capture the whole site, not one pageAccepted2026-06-03 (Phase 2 deviation noted 2026-06-04)—
0034Design-system-first capture as the primary path———
0035Onion-layered design paradigm: unified canvas with rule-locked DS cascadeAccepted (paradigm direction locked; mechanics in design — see Open engineering questions)2026-06-04—
0036Foundation v1: default project starter + 50-component library + 100-icon set + WCAG-locked rule cascadeAccepted (paradigm direction); component-level specs frozen for v12026-06-04—
0037WCAG override storage + auditAccepted2026-06-06—
0038Brand layer persistenceAccepted2026-06-06—
0039Foundation upgrade path (v1 → v2 → v3)Accepted2026-06-06—
0040RTL icon opt-outAccepted2026-06-06—
0041User-added custom iconsAccepted2026-06-06—
0042SSR / SSG theme inlining (no-flash)Accepted2026-06-06—
0043Inter subset coverage (Vietnamese / SEA + extended Latin / Greek)Accepted (documents current behavior + locks the policy)2026-06-06—
0044Component variant API UXAccepted2026-06-06—
0045Composite typography: live refs, not frozen snapshotsAccepted2026-06-06—
0046Icon set v2 roadmap: 7 → 100 → 300Accepted2026-06-06—
0047Foundation icons sourced from Phosphor (amends ADR 0036 §4 / ADR 0046)Accepted2026-06-06—
0048Colors raison d'être: Foundation as default brand, mentor at every narrow placeAccepted2026-06-07—
0049Arno Sorgente: ARNO self-hosts its own UI (test project → main)Proposed (design spec, not yet implemented)2026-06-07—
0050Arno Foundation evolution via its own self-hosting projectProposed (design spec)2026-06-07—
0051Workflow tab inside Arno Sorgente shows the live ARNO product treeProposed (design spec, separate session work)2026-06-07—
0052Arno Sorgente: shared-DB architecture (supersedes 0049's implementation approach)Accepted — amended 2026-07-03 (storage location, see Amendment below)2026-06-08—
0053Sorgente architecture onto Foundation rulesAccepted2026-06-08—
0054Sorgente as a Library surfaceAccepted2026-06-09—
0055Sorgente layout overrides + context menuAccepted2026-06-09—
0056Studio layout tree (drag-rearrangeable Sorgente surfaces)Accepted2026-06-09Sorgente Studio
0057Sorgente component contractAccepted2026-06-10—
0058Studio tools documentation pattern (11-file canonical set)Accepted (codifies existing convention; now load-bearing)2026-06-18—
0059Italian / Renaissance naming chord for Studio tools and product surfacesAccepted (codifies existing convention; now load-bearing)2026-06-18—
0060Documentation lives under docs/, code under apps/ and packages/ — separation by conventionAccepted (codifies existing convention; rejects collocation alternatives)2026-06-18—
0061layerTypeOf(node) as the single layer-type dispatch authority across StudioAccepted (codifies existing convention; load-bearing cross-tool contract)2026-06-18—
0062Carrier contract: data-arno-box-id as the single positioning anchor across StudioAccepted (codifies existing convention; load-bearing cross-tool contract)2026-06-18—
0063Studio tools as per-tool reusable packages over a shared ponte kernelAccepted2026-07-12—
0066Server persistence for Workflow composition artboardsAccepted2026-07-14—
0067Workflow section: two header tabs (Workflow + Screen), Screen as an adaptive canvasAccepted — §Decision.2 & invariant W2 superseded by ADR 0069 (2026-07-14; Workflow tab is the artboard Studio editor, Tela present on both tabs)2026-07-14—
0068Save artboard box → project Component Library (Copy)Accepted2026-07-14—
0069Workflow tab hosts the artboard Studio editor (supersedes ADR 0067 §Decision.2 + W2)Accepted; §Decision.2 + W2 (below) superseded 2026-07-27 by the2026-07-14—
0071Sorgente gets a real project row for Workflow/Screen persistenceAccepted2026-07-16—
0072Server persistence for Workflow artboard prototype links (tavola)Accepted2026-07-16—
0073Generic entity-link connector (tavola supersedes artboard-only)Accepted2026-07-17—
0074StepBack: one back/forward (undo/redo) module———
0075Terminology split: filo (connector) vs tavola (artboard+tree domain)Accepted2026-07-17—
0076Albero (artboard tree toggle) and Rotta (connection-arrow overlay)Accepted2026-07-17—
0077@arno/compasso: consolidating ruler + zoom/pan into one reusable packageAccepted2026-07-20—
0078Punta blocks + variantsAccepted — all 8 blocks extracted + sidebars thinned; central-registry inversion deliberately deferred (see Migration)2026-07-27—
0079@arno/compasso owns fit-to-screen and the --artboard-zoom world-zoom contractAccepted2026-07-29—
0080Marca: the brandbook-PDF import module (naming + code↔UI split)Accepted2026-08-05—
0081Sorgente as upstream: one-way, override-preserving project inheritanceProposed (design spec — architecture-first; no code shipped this run)2026-08-06—
0082Per-project repo hosting under Arno's org + monetized developer-share (reseller model)Proposed (design spec — architecture-first; no code, gated on maintainer-provisioned infra)2026-08-06—
0083px-canon storage, rem-emit contract, and root-preview as a verifierAccepted2026-08-08—
0084Garzone: the in-Studio AI assistant (provider-agnostic, tree-acting)———
00850085. Garzone agent loop runs in the browser client; the Worker is a per-turn proxy———
00860086. Garzone is grounded in the project's design tokens by a client-composed prompt + a role-aware guard———
0087Component Model integration (Property/State/Behaviour/Proof + tokens)Accepted (design). Execution phased Ф0–Ф7.2026-08-20—
0089Merge queue for the shared Studio trunkAccepted2026-09-07—

Feature: Cross-cutting perf pattern для /app/* route changes

#TitleStatusDatePhase / Feature
0026Navigation performance paradigmAccepted2026-05-27Cross-cutting perf pattern для /app/* route changes

Feature: Layout Grid Engine

#TitleStatusDatePhase / Feature
0020Layout Grid: recursive Container/Content tree as foundation for all Arno pagesAccepted2026-05-25Layout Grid Engine (product-level core)

Feature: Phase 3 Layout Grid

#TitleStatusDatePhase / Feature
0025Adaptive overrides + Tokens publish flowAccepted2026-05-26Phase 3 Layout Grid (ADR 0020)

Feature: Responsive Columns

#TitleStatusDatePhase / Feature
0064Columns (Switcher) responsive to Tela widthAccepted2026-07-14Responsive Columns

Feature: Responsive primitives

#TitleStatusDatePhase / Feature
0065Generalize per-width primitive overrides (propsAt)Accepted2026-07-14Responsive primitives (Tela-width overrides)

Feature: Tela viewport / responsive primitives

#TitleStatusDatePhase / Feature
0070Per-project Tela default viewportAccepted2026-07-14Tela viewport / responsive primitives

Feature: URL-import

#TitleStatusDatePhase / Feature
0007URL-import: code-first, не vision-firstAccepted2026-05-22URL-import (unparks §V "Small-company path / ARNO Studio")
0008Hybrid stack: schema-driven priority chains + reactive visionAccepted2026-05-22URL-import
0009Acceptance gate: 3 эмпирических bool, не weighted scoresAccepted2026-05-22URL-import
0010Completeness: матрица combinations, не point checkAccepted2026-05-22URL-import
0011Vision activation: reactive, не predictiveAccepted2026-05-22URL-import
0012Uniqueness: user decides, не algorithmAccepted2026-05-22URL-import
0013"Чем дольше живём — тем меньше платим" как hard requirementAccepted2026-05-22URL-import
0014Legal-clean distillation: Qwen teacher, не Anthropic/OpenAIAccepted2026-05-22URL-import (data flywheel — ADR 0013)
0015Explicit non-use of Claude API в URL-import stackAccepted2026-05-22URL-import
0016V1 staging area вместо direct git commitAccepted2026-05-22URL-import
0017Shadow data: ToS-based disclosure, не registration checkboxAccepted2026-05-22URL-import (data flywheel — ADR 0013)
0018Atom embeddings: E5-small text, не DINOv2 visualAccepted2026-05-22URL-import (atoms — cache L3)
0019Extension capture path: Camp 1 persistence + multi-provider auth + 5-phase roadmapAccepted2026-05-24URL-import (Extension MVP — §V «Small-company path / ARNO Studio» continuation)

{/* AUTOGEN:adr-index END */}

Lifecycle

  • Proposed → drafted, не reviewed
  • Accepted → reviewed, applied к master spec
  • Deprecated → no longer relevant но preserved для history
  • Superseded by ADR-XXXX → replaced by newer decision

ADRs никогда не удаляются — history immutable. Status changes reflect evolution.

Связь с master spec

После acceptance ADR:

  1. Master spec _index.md updated (version bump, changelog entry с ADR reference)
  2. Affected sections rewritten
  3. Parking list updated если applicable
  4. ADR remains canonical "почему" для решения; master spec — canonical "что" сейчас
API referenceADR 001 — Static export now, edge adapter when Auth/API land