Skip to content

INDEX.md

Latest commit

 

History

History
137 lines (107 loc) · 10.1 KB

INDEX.md

File metadata and controls

137 lines (107 loc) · 10.1 KB
Raw

Architecture Decision Records (ADRs)

Purpose: Documents architectural decisions for the Spaarke platform Audience: Developers, architects, AI coding agents Last Updated: 2026-02-23

About ADRs

Architecture Decision Records capture important architectural decisions made during the development of Spaarke, including the context, decision, and consequences.

ADR Index

ADR Title Domain Status
ADR-001 Minimal API and BackgroundService Workers Backend Accepted
ADR-002 Thin Dataverse Plugins Dataverse Accepted
ADR-003 Lean Authorization Seams Security Accepted
ADR-004 Async Job Contract Backend Accepted
ADR-005 Flat Storage for SPE Storage Accepted
ADR-006 Anti-Legacy-JS: PCF for Form Controls, React Code Pages for Dialogs Frontend Accepted
ADR-007 SPE Storage Seam Minimalism Storage Accepted
ADR-008 Authorization Endpoint Filters Security Accepted
ADR-009 Redis-First Caching Strategy Caching Accepted
ADR-010 Dependency Injection Minimalism Backend Accepted
ADR-011 Dataset PCF for Form-Embedded List Controls Frontend Accepted
ADR-012 Shared Component Library Frontend Accepted
ADR-013 AI Tool Framework Architecture AI Accepted
ADR-014 AI Caching and Reuse Policy AI Accepted
ADR-015 AI Data Governance AI Accepted
ADR-016 AI Cost, Rate Limits, Backpressure AI Accepted
ADR-017 Async Job Status and Persistence Backend Accepted
ADR-018 Feature Flags and Kill Switches Operations Accepted
ADR-019 API Errors and ProblemDetails Backend Accepted
ADR-020 Versioning Strategy Operations Accepted
ADR-021 Fluent UI v9 Design System UI/UX Accepted
ADR-022 PCF Platform Libraries — Field-Bound Controls Only Frontend Accepted
ADR-023 Choice Dialog Pattern Frontend Accepted
ADR-026 Full-Page Custom Page Standard Frontend Accepted
ADR-027 Subscription Isolation & Dataverse Solution Management Operations Proposed
ADR-029 BFF Publish Hygiene (framework-dependent linux-x64, sourcemap exclusion, transitive CVE overrides, size baseline) Backend / Operations Accepted
ADR-030 BFF Null-Object Kill-Switch Pattern (P1/P2/P3 patterns; FeatureDisabledException → 503 ProblemDetails; closes RB-T028 cluster) Backend / API Accepted
ADR-034 User-Record Membership Resolution Pattern (discovery-based MembershipResolverService + 6-path identity normalization + Phase 2 junction table sprk_userentityassociation + Service Bus topic sprk-membership-changes; LookupUserMembership playbook node ActionType=52; closes A1/D5 root cause from R2 UAT) Backend / AI / Dataverse Accepted (R3 Part 1, 2026-06-21)
ADR-036 Background-Job Infrastructure (Spaarke.Scheduling — shared lib + IScheduledJob contract + ScheduledJobHost + Cronos cron parsing + sprk_backgroundjob* Dataverse entities + /api/admin/jobs/* admin surface; two reference consumers: MembershipReconciliationJob + migrated PlaybookSchedulerJob) Backend / Scheduling Accepted (R3 Part 2, 2026-06-21)
ADR-037 Multi-Node Output Composition (NodeType.DeliverComposite + ActionType.DeliverComposite=42; per-section SSE streaming; FE widget rework to sections-by-name; reduces 5 brittle coordination points to 2) AI / BFF / FE Accepted (chat-routing-redesign-r1 Phase 5R Wave 5-C, 2026-06-25)
ADR-038 Testing Strategy — Integration-heavy pyramid, 6 KEEP path categories as MUST rules (auth/regression/data-mutation/tenant/contract/domain), coverage as observation never gate, ban Mock<HttpMessageHandler> + DI-registration + ctor null-check tests, TimeProvider over Stopwatch. STANDALONE — does NOT supersede ADR-022 (PCF Platform Libraries — unrelated frontend scope). Testing / Backend Accepted (ci-cd-unit-test-remediation-r1 Phase 1 Stream B, 2026-06-26)
ADR-045 Communication Architecture — canonical <EmailComposer/> send (1 engine + 3 wrappers + sendCommunication()) + Association Engine over a normalized envelope (8 targets; deterministic-first rungs 0–3 then semantic 4 + AI 5; confidence + provenance) + direction-agnostic ICommunicationEnrichmentService (both directions, adds outbound RAG) + channel seams (email impl only); auto-file ON deterministic ≥0.85 (ADR-018 kill-switch; AI rungs never auto-file); org target sprk_organization; retires OOB-email/SSS. Supersedes the never-written R3 "ADR-033" plan Communication / BFF / FE Accepted (email-communication-solution-r4, 2026-07-14)

ADRs by Domain

Frontend / UI

ADR Summary
ADR-021 Authoritative UI/UX standard: Fluent v9, dark mode, accessibility. React version differs by surface — PCF: 16/17 (platform); Code Pages: 18 (bundled).
ADR-006 Anti-legacy-JS: PCF for form-bound controls; React Code Pages for standalone dialogs/pages. No new legacy JS webresources.
ADR-011 Dataset PCF for list-based UI embedded on forms. Standalone dialogs with list/search UI → React Code Page.
ADR-012 Shared component library (@spaarke/ui-components): peerDependencies >=16.14.0 to support both PCF (React 16/17) and Code Pages (React 18). Includes WizardDialog and SidePanel.
ADR-022 PCF controls (field-bound only): React 16/17 APIs, platform-provided. React Code Pages use React 18 bundled — NOT subject to this ADR.

Backend / API

ADR Summary
ADR-001 .NET Minimal API with BackgroundService
ADR-004 Async job patterns
ADR-010 Lean DI registrations
ADR-017 Job status persistence
ADR-019 ProblemDetails for errors
ADR-029 BFF publish hygiene: framework-dependent linux-x64, sourcemap exclusion, surgical transitive CVE overrides, size baseline ratchet
ADR-030 BFF Null-Object kill-switch pattern: conditional service consumed by unconditional endpoint → Null-Object in else-branch (P1/P2/P3); FeatureDisabledException → 503 ProblemDetails per ADR-018/019

AI Features

ADR Summary
ADR-013 AI Tool Framework architecture
ADR-014 AI response caching
ADR-015 AI data handling rules
ADR-016 AI cost controls

Security

ADR Summary
ADR-003 Authorization patterns
ADR-008 Endpoint filter authorization

Storage / Caching

ADR Summary
ADR-005 SPE flat storage model
ADR-007 Storage abstraction
ADR-009 Redis-first caching

Dataverse

ADR Summary
ADR-002 Thin plugins, no HTTP calls

Operations

ADR Summary
ADR-018 Feature flag patterns
ADR-020 Versioning strategy
ADR-027 Subscription isolation, managed solutions, Dataverse CI/CD

For AI Agents

Concise versions: AI-optimized summaries (~100-150 lines) are in .claude/adr/

When to load ADRs:

  • Before creating new components
  • When making architectural changes
  • To understand constraints and patterns

Key ADRs for UI work:

  • Always load ADR-021 for any UI component work (design system, theming, React version by surface).
  • Load ADR-006 when choosing between PCF and React Code Page.
  • Load ADR-022 when working on PCF controls (field-bound only).

Two-tier UI architecture (ADR-006):

  • Field-bound form controls → PCF (src/client/pcf/) — React 16/17, platform-provided
  • Standalone dialogs/pages → React Code Page (src/client/code-pages/) — React 18, bundled
  • Shared components → src/client/shared/Spaarke.UI.Components/ — both surfaces

Related Resources