azcodr 1.5.2 → 2.0.0

package/docs/rules/requirements_engineering.md

@@ -1,98 +1,98 @@
-# Requirements Engineering, INVEST Stories & Gherkin Criteria
-
-> **Core Mandate:** Decompose business requirements into vertically sliced INVEST user stories, executable Gherkin acceptance criteria, and exhaustive edge case matrices, acknowledging that stories are conversation starters rather than full specification documents.
-
----
-
-## 1. Are User Stories Requirements?
-
-In modern product engineering (per Scrum.org and XP principles), **user stories are NOT requirements**. Rather, a user story is one specific, highly effective technique used to *express, capture, and explore* user-centric requirements.
-
-### Key Distinctions
-- **A Token for Conversation:** A user story is a "placeholder" or token promising a future conversation. It captures the essence, not every granular detail upfront.
-- **The "Pidgin Language" Bridge:** A pidgin language is a simplified common language that allows people with different native tongues to trade and work together. User stories act as a pidgin language bridging the business/customer perspective and the software engineering architecture without forcing either side to abandon their domain language.
-- **Ron Jeffries' 3 C's of User Stories:**
-  1. **Card:** The physical index card or digital ticket capturing the intent (`As a... I want to... So that...`).
-  2. **Conversation:** The collaborative discussion between Product Owner, stakeholders, and developers where details and trade-offs are co-created.
-  3. **Confirmation:** The executable acceptance criteria and automated tests that prove whether the story satisfies its intent.
-
-### Non-Story Requirements
-Not all system requirements originate from an end-user persona or fit the user story syntax. High-integrity systems also require:
-- **System Invariants:** Core domain rules (e.g., "A transaction cannot be completed without a verified payment instrument").
-- **Non-Functional Requirements (NFRs):** Latency SLAs, encryption standards, concurrency limits, and accessibility compliance (WCAG 2.2 AA).
-- **Architectural Spikes:** Time-boxed exploratory investigations to resolve technical unknowns.
-- **Regulatory & Security Controls:** SOC 2 audit log immutability, GDPR data erasure rights, and OWASP Top 10 defenses.
-
-These requirements should be operationalized as explicit acceptance constraints, architectural fitness functions, or dedicated technical backlog items.
-
----
-
-## 2. INVEST User Story Framework & Vertical Cake Slicing
-
-Ensure every user story satisfies Bill Wake's **INVEST** criteria:
-
-- **I - Independent:** Sliced vertically to minimize conceptual overlap. Can be scheduled, implemented, and released in any sequence without blocking peer stories.
-- **N - Negotiable:** Captures the core essence and problem space, not a rigid implementation contract. Specific details are co-created during pair programming and TDD.
-- **V - Valuable:** Delivers observable, direct benefit to the customer or business stakeholder.
-- **E - Estimable:** Well-understood and right-sized so the team can gauge complexity. Unknowns are resolved via prior time-boxed spikes.
-- **S - Small:** Sized to be completed within 1–2 development days. Small stories yield higher estimation accuracy and rapid feedback.
-- **T - Testable:** Accompanied by concrete pass/fail assertions. Non-functional requirements are operationalized into automated tests early.
-
-### The Multi-Layer Cake Metaphor (Vertical Slicing)
-Think of a complete feature as a multi-layer cake:
-```mermaid
-flowchart TD
-    subgraph Cake["The Multi-Layer Cake (Vertical Slicing)"]
-        direction TB
-        L1["Presentation / UI Layer"]
-        L2["Business Logic & Application Use Case"]
-        L3["Domain Invariants & Entities"]
-        L4["Persistence & Database Layer"]
-        L1 --- L2 --- L3 --- L4
-    end
-
-    Slice["Vertical Cake Slice<br/>(Customer gets a taste of every layer)"]
-    Slice --> L1
-    Slice --> L2
-    Slice --> L3
-    Slice --> L4
-```
-- **Horizontal Slicing (Anti-Pattern):** Implementing only the database schema or only the UI mock. A full database table has zero observable value to the customer without presentation and logic layers.
-- **Vertical Slicing (Golden Standard):** Slicing thin through all layers (UI ➔ API ➔ Domain ➔ DB). Even a minimal vertical slice provides working functionality that can be deployed, tested, and validated empirically.
-
----
-
-## 3. Executable Gherkin Acceptance Criteria
-
-Draft concrete, actionable scenarios directly convertible into automated acceptance tests:
-
-```gherkin
-Scenario: Successful Digital Agreement Execution
-  Given an authenticated customer with an approved application
-  And the agreement is in "PENDING_SIGNATURE" status
-  When the customer provides their legal name "Alice Smith" and confirms agreement
-  Then the response status is 200 OK
-  And the agreement status transitions to "ACTIVE"
-  And an execution audit record is persisted with timestamp, actorId, and IP address
-  And a transactional confirmation notification is queued for delivery
-```
-
-### Writing Rules for Gherkin Scenarios
-- **Use Active Voice:** State explicit actor actions (`When the user clicks "Confirm Agreement"` rather than passive `When the button is clicked`).
-- **One Observable Behavior Per Scenario:** Focus each scenario on one specific state transition or business invariant.
-- **Cover Both Happy and Unhappy Paths:** Every feature must include positive paths and negative failure assertions.
-
----
-
-## 4. Negative Scope & Edge Case Matrices
-
-- **Out-of-Scope (Non-Goals):** Explicitly document what will NOT be built in this increment to prevent scope creep and align expectations.
-- **Edge Case Matrix:** Map all potential failure states to standardized RFC 7807 problem details and HTTP status codes:
-  - `400 Bad Request`: Schema validation failures, missing required fields.
-  - `401 Unauthorized`: Missing or invalid session tokens.
-  - `403 Forbidden`: Cross-tenant boundary violations, role privilege deficits.
-  - `404 Not Found`: Resource non-existence (or masked enumeration).
-  - `409 Conflict`: Duplicate unique constraints, state machine transition invalidity.
-  - `422 Unprocessable Entity`: Semantic domain invariant violations.
-  - `429 Too Many Requests`: Rate limiter token exhaustion.
-  - `500 Internal Server Error`: Unhandled upstream infrastructure failures.
+# Requirements Engineering, INVEST Stories & Gherkin Criteria
+
+> **Core Mandate:** Decompose business requirements into vertically sliced INVEST user stories, executable Gherkin acceptance criteria, and exhaustive edge case matrices, acknowledging that stories are conversation starters rather than full specification documents.
+
+---
+
+## 1. Are User Stories Requirements?
+
+In modern product engineering (per Scrum.org and XP principles), **user stories are NOT requirements**. Rather, a user story is one specific, highly effective technique used to *express, capture, and explore* user-centric requirements.
+
+### Key Distinctions
+- **A Token for Conversation:** A user story is a "placeholder" or token promising a future conversation. It captures the essence, not every granular detail upfront.
+- **The "Pidgin Language" Bridge:** A pidgin language is a simplified common language that allows people with different native tongues to trade and work together. User stories act as a pidgin language bridging the business/customer perspective and the software engineering architecture without forcing either side to abandon their domain language.
+- **Ron Jeffries' 3 C's of User Stories:**
+  1. **Card:** The physical index card or digital ticket capturing the intent (`As a... I want to... So that...`).
+  2. **Conversation:** The collaborative discussion between Product Owner, stakeholders, and developers where details and trade-offs are co-created.
+  3. **Confirmation:** The executable acceptance criteria and automated tests that prove whether the story satisfies its intent.
+
+### Non-Story Requirements
+Not all system requirements originate from an end-user persona or fit the user story syntax. High-integrity systems also require:
+- **System Invariants:** Core domain rules (e.g., "A transaction cannot be completed without a verified payment instrument").
+- **Non-Functional Requirements (NFRs):** Latency SLAs, encryption standards, concurrency limits, and accessibility compliance (WCAG 2.2 AA).
+- **Architectural Spikes:** Time-boxed exploratory investigations to resolve technical unknowns.
+- **Regulatory & Security Controls:** SOC 2 audit log immutability, GDPR data erasure rights, and OWASP Top 10 defenses.
+
+These requirements should be operationalized as explicit acceptance constraints, architectural fitness functions, or dedicated technical backlog items.
+
+---
+
+## 2. INVEST User Story Framework & Vertical Cake Slicing
+
+Ensure every user story satisfies Bill Wake's **INVEST** criteria:
+
+- **I - Independent:** Sliced vertically to minimize conceptual overlap. Can be scheduled, implemented, and released in any sequence without blocking peer stories.
+- **N - Negotiable:** Captures the core essence and problem space, not a rigid implementation contract. Specific details are co-created during pair programming and TDD.
+- **V - Valuable:** Delivers observable, direct benefit to the customer or business stakeholder.
+- **E - Estimable:** Well-understood and right-sized so the team can gauge complexity. Unknowns are resolved via prior time-boxed spikes.
+- **S - Small:** Sized to be completed within 1–2 development days. Small stories yield higher estimation accuracy and rapid feedback.
+- **T - Testable:** Accompanied by concrete pass/fail assertions. Non-functional requirements are operationalized into automated tests early.
+
+### The Multi-Layer Cake Metaphor (Vertical Slicing)
+Think of a complete feature as a multi-layer cake:
+```mermaid
+flowchart TD
+    subgraph Cake["The Multi-Layer Cake (Vertical Slicing)"]
+        direction TB
+        L1["Presentation / UI Layer"]
+        L2["Business Logic & Application Use Case"]
+        L3["Domain Invariants & Entities"]
+        L4["Persistence & Database Layer"]
+        L1 --- L2 --- L3 --- L4
+    end
+
+    Slice["Vertical Cake Slice<br/>(Customer gets a taste of every layer)"]
+    Slice --> L1
+    Slice --> L2
+    Slice --> L3
+    Slice --> L4
+```
+- **Horizontal Slicing (Anti-Pattern):** Implementing only the database schema or only the UI mock. A full database table has zero observable value to the customer without presentation and logic layers.
+- **Vertical Slicing (Golden Standard):** Slicing thin through all layers (UI ➔ API ➔ Domain ➔ DB). Even a minimal vertical slice provides working functionality that can be deployed, tested, and validated empirically.
+
+---
+
+## 3. Executable Gherkin Acceptance Criteria
+
+Draft concrete, actionable scenarios directly convertible into automated acceptance tests:
+
+```gherkin
+Scenario: Successful Digital Agreement Execution
+  Given an authenticated customer with an approved application
+  And the agreement is in "PENDING_SIGNATURE" status
+  When the customer provides their legal name "Alice Smith" and confirms agreement
+  Then the response status is 200 OK
+  And the agreement status transitions to "ACTIVE"
+  And an execution audit record is persisted with timestamp, actorId, and IP address
+  And a transactional confirmation notification is queued for delivery
+```
+
+### Writing Rules for Gherkin Scenarios
+- **Use Active Voice:** State explicit actor actions (`When the user clicks "Confirm Agreement"` rather than passive `When the button is clicked`).
+- **One Observable Behavior Per Scenario:** Focus each scenario on one specific state transition or business invariant.
+- **Cover Both Happy and Unhappy Paths:** Every feature must include positive paths and negative failure assertions.
+
+---
+
+## 4. Negative Scope & Edge Case Matrices
+
+- **Out-of-Scope (Non-Goals):** Explicitly document what will NOT be built in this increment to prevent scope creep and align expectations.
+- **Edge Case Matrix:** Map all potential failure states to standardized RFC 9457 problem details and HTTP status codes:
+  - `400 Bad Request`: Schema validation failures, missing required fields.
+  - `401 Unauthorized`: Missing or invalid session tokens.
+  - `403 Forbidden`: Cross-tenant boundary violations, role privilege deficits.
+  - `404 Not Found`: Resource non-existence (or masked enumeration).
+  - `409 Conflict`: Duplicate unique constraints, state machine transition invalidity.
+  - `422 Unprocessable Entity`: Semantic domain invariant violations.
+  - `429 Too Many Requests`: Rate limiter token exhaustion.
+  - `500 Internal Server Error`: Unhandled upstream infrastructure failures.

package/docs/rules/security_compliance.md

@@ -1,53 +1,53 @@
-# Application Security, Cryptography & Regulatory Compliance
-
-> **Core Mandate:** Enforce OWASP Top 10 security defenses, cryptographic rigor, token bucket rate limiting, SOC 2 Type II security controls, ISO/IEC 27001 standards, and GDPR data erasure rights.
-
----
-
-## 1. OWASP Top 10 Application Security Defenses
-
-Production software must systematically eliminate OWASP Top 10 attack vectors:
-
-1. **Injection Defense (SQL / Command / LDAP)**:
-   - Always use parameterized queries and prepared statements. Never concatenate untrusted strings into database queries or shell command strings.
-2. **Cross-Site Scripting (XSS)**:
-   - Standardize on modern framework auto-escaping (React, Vue, Svelte). Strictly forbid `dangerouslySetInnerHTML` or `v-html` unless sanitized by a verified sanitizer (e.g. DOMPurify).
-3. **Server-Side Request Forgery (SSRF)**:
-   - When fetching URLs provided by users, validate hostnames against an explicit domain allowlist. Never make outbound requests to private RFC 1918 subnets (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) or cloud metadata endpoints (`169.254.169.254`).
-4. **Security Misconfiguration & Headers**:
-   - Enforce secure HTTP response headers:
-     ```http
-     Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
-     X-Content-Type-Options: nosniff
-     X-Frame-Options: DENY
-     Content-Security-Policy: default-src 'self'; script-src 'self';
-     ```
-
----
-
-## 2. Cryptographic Standards & Rate Limiting
-
-### Cryptographic Rigor
-- **Password Hashing**: Use **Argon2id** (minimum 64MB memory, 3 iterations) or **bcrypt** (work factor $\ge 12$). Never use SHA-256, SHA-1, or MD5 for password storage.
-- **Data Encryption at Rest**: Encrypt sensitive PII, access tokens, and secrets using **AES-256-GCM** or **ChaCha20-Poly1305** with authenticated encryption.
-- **Data in Transit**: Mandate **TLS 1.3** across all external and internal microservice communication.
-
-### Distributed Rate Limiting
-Protect APIs against brute force, scraping, and denial-of-service (DoS) attacks using a distributed Token Bucket or Leaky Bucket algorithm backed by Redis:
-- **Authentication Endpoints (`/login`, `/signup`)**: Strict limit of 5 requests per minute per IP.
-- **Public API Endpoints**: Default limit of 100 requests per minute per IP/API token.
-- **Response Headers**: Return RFC 6585 headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `429 Too Many Requests` when exceeded.
-
----
-
-## 3. Regulatory Compliance: SOC 2, ISO 27001 & GDPR
-
-All systems handling sensitive, customer, or enterprise data must satisfy fundamental compliance controls:
-
-1. **Immutable Audit Trails (SOC 2 CC6.8 / ISO 27001 A.12.4)**:
-   - All state mutations, privilege changes, and authentication events must write to an immutable audit log recording: `timestamp`, `actorId`, `tenantId`, `action`, `resourceId`, `clientIp`, and `userAgent`.
-   - Audit logs must be retained in append-only storage and protected from tampering or deletion.
-2. **GDPR Data Erasure Rights (Article 17 "Right to be Forgotten")**:
-   - Systems must provide an automated data erasure pipeline capable of permanently deleting or cryptographically pseudonymizing user PII across all databases and backups within 30 days of a verified request.
-3. **Least Privilege Access (SOC 2 CC6.1)**:
-   - Developers and runtime services must operate under strict principle of least privilege. Production database credentials and encryption keys must never be accessible in local development environments.
+# Application Security, Cryptography & Regulatory Compliance
+
+> **Core Mandate:** Enforce OWASP Top 10 security defenses, cryptographic rigor, token bucket rate limiting, SOC 2 Type II security controls, ISO/IEC 27001 standards, and GDPR data erasure rights.
+
+---
+
+## 1. OWASP Top 10 Application Security Defenses
+
+Production software must systematically eliminate OWASP Top 10 attack vectors:
+
+1. **Injection Defense (SQL / Command / LDAP)**:
+   - Always use parameterized queries and prepared statements. Never concatenate untrusted strings into database queries or shell command strings.
+2. **Cross-Site Scripting (XSS)**:
+   - Standardize on modern framework auto-escaping (React, Vue, Svelte). Strictly forbid `dangerouslySetInnerHTML` or `v-html` unless sanitized by a verified sanitizer (e.g. DOMPurify).
+3. **Server-Side Request Forgery (SSRF)**:
+   - When fetching URLs provided by users, validate hostnames against an explicit domain allowlist. Never make outbound requests to private RFC 1918 subnets (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) or cloud metadata endpoints (`169.254.169.254`).
+4. **Security Misconfiguration & Headers**:
+   - Enforce secure HTTP response headers:
+     ```http
+     Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+     X-Content-Type-Options: nosniff
+     X-Frame-Options: DENY
+     Content-Security-Policy: default-src 'self'; script-src 'self';
+     ```
+
+---
+
+## 2. Cryptographic Standards & Rate Limiting
+
+### Cryptographic Rigor
+- **Password Hashing**: Use **Argon2id** (minimum 64MB memory, 3 iterations) or **bcrypt** (work factor $\ge 12$). Never use SHA-256, SHA-1, or MD5 for password storage.
+- **Data Encryption at Rest**: Encrypt sensitive PII, access tokens, and secrets using **AES-256-GCM** or **ChaCha20-Poly1305** with authenticated encryption.
+- **Data in Transit**: Mandate **TLS 1.3** across all external and internal microservice communication.
+
+### Distributed Rate Limiting
+Protect APIs against brute force, scraping, and denial-of-service (DoS) attacks using a distributed Token Bucket or Leaky Bucket algorithm backed by Redis:
+- **Authentication Endpoints (`/login`, `/signup`)**: Strict limit of 5 requests per minute per IP.
+- **Public API Endpoints**: Default limit of 100 requests per minute per IP/API token.
+- **Response Headers**: Return RFC 6585 headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `429 Too Many Requests` when exceeded.
+
+---
+
+## 3. Regulatory Compliance: SOC 2, ISO 27001 & GDPR
+
+All systems handling sensitive, customer, or enterprise data must satisfy fundamental compliance controls:
+
+1. **Immutable Audit Trails (SOC 2 CC6.8 / ISO 27001 A.12.4)**:
+   - All state mutations, privilege changes, and authentication events must write to an immutable audit log recording: `timestamp`, `actorId`, `tenantId`, `action`, `resourceId`, `clientIp`, and `userAgent`.
+   - Audit logs must be retained in append-only storage and protected from tampering or deletion.
+2. **GDPR Data Erasure Rights (Article 17 "Right to be Forgotten")**:
+   - Systems must provide an automated data erasure pipeline capable of permanently deleting or cryptographically pseudonymizing user PII across all databases and backups within 30 days of a verified request.
+3. **Least Privilege Access (SOC 2 CC6.1)**:
+   - Developers and runtime services must operate under strict principle of least privilege. Production database credentials and encryption keys must never be accessible in local development environments.

package/docs/rules/server_driven_ui.md

@@ -1,88 +1,88 @@
-# Server-Driven UI (SDUI) & Dynamic Theming
-
-> **Core Mandate:** Enforce metadata-driven UI rendering from declarative backend schemas, eliminating client-side tenant code forks, and inject white-label branding via W3C Design Tokens (DTCG).
-
----
-
-## 1. The YAGNI Gate: Static Client Components vs. Server-Driven UI
-
-Server-Driven UI requires building and maintaining a JSON schema specification, schema versioning, validation, and multi-platform component interpreters. **Never build a Server-Driven UI when standard client-side components and modern web deployments solve the problem.**
-
-```mermaid
-flowchart TD
-    subgraph SDUIGate["Server-Driven UI YAGNI Gate"]
-        B1["1. Simple Baseline (Day 1)<br/>• Standard React/JSX components styled with Tailwind CSS<br/>• Instant web deployments via continuous delivery<br/>• Zero dynamic layout interpreters or backend schema JSONs"]
-        B2["2. Anti-Triggers (Forbidden)<br/>• Web-only SaaS dashboards, internal admin tools, or landing pages<br/>• Early-stage products iterating on UI layouts<br/>• Teams without multi-platform client parity requirements"]
-        B3["3. The Tipping Point (Graduation)<br/>• Native mobile apps (iOS/Android) where app store review cycles delay urgent UI/flow mutations<br/>• Multi-tenant white-label products where customers dynamically construct custom form layouts<br/>• Cross-platform parity: 1 backend drives layout across Web, iOS SwiftUI, and Android Jetpack Compose"]
-        B1 -->|Forbidden if web-only or early| B2
-        B1 -->|Triggered by multi-platform or white-label| B3
-    end
-```
-
----
-
-## 2. Declarative Client-Agnostic SDUI Schema
-
-The backend provides a declarative UI layout schema describing fields, layouts, dynamic visibility rules (via Common Expression Language or JSON expressions), and allowed actions (`_actions`):
-
-```json
-{
-  "view": "OrderEdit",
-  "layout": "two-column",
-  "sections": [
-    {
-      "id": "general",
-      "title": "General Details",
-      "components": [
-        { "type": "TextInput", "id": "orderNumber", "label": "Order #", "readOnly": true },
-        { "type": "TextInput", "id": "custom_attributes.poNumber", "label": "PO Number", "required": true }
-      ]
-    },
-    {
-      "id": "tax",
-      "title": "Tax Exemption",
-      "visibleIf": "order.custom_attributes.isTaxExempt == true",
-      "components": [
-        { "type": "TextInput", "id": "custom_attributes.taxExemptionId", "label": "Tax ID", "required": true }
-      ]
-    }
-  ],
-  "_actions": [
-    { "action": "SUBMIT_FOR_APPROVAL", "label": "Submit Order", "method": "POST", "target": "/api/v1/orders/123/submit" }
-  ]
-}
-```
-
----
-
-## 3. Multi-Platform Component Registries
-
-Frontend clients (Web, Mobile, Desktop) never contain hardcoded tenant branching. Each platform implements a local **Component Registry** mapping backend descriptors to native platform primitives:
-
-- **Web Clients**: Rendered dynamically via accessible primitives (Web Components, React, Vue, Svelte, or Solid).
-- **Mobile Clients**: Rendered natively via Flutter, iOS SwiftUI, or Android Jetpack Compose.
-- **Desktop Clients**: Rendered natively via Tauri or cross-platform toolkits.
-
----
-
-## 4. Universal Design Tokens (W3C DTCG Standard)
-
-Manage tenant white-label branding and design systems via the **W3C Design Tokens Community Group (DTCG)** specification:
-
-```json
-{
-  "color": {
-    "brand": {
-      "primary": { "$value": "#1e40af", "$type": "color" },
-      "accent": { "$value": "#f59e0b", "$type": "color" }
-    }
-  },
-  "dimension": {
-    "radius": {
-      "base": { "$value": "6px", "$type": "dimension" }
-    }
-  }
-}
-```
-
-- **Universal Compilation**: Process tenant `tokens.json` files using **Style Dictionary** to compile dynamic themes at runtime for CSS Custom Properties (`--color-brand-primary`), Android XML / Compose, and iOS Swift tokens without code redeployments.
+# Server-Driven UI (SDUI) & Dynamic Theming
+
+> **Core Mandate:** Enforce metadata-driven UI rendering from declarative backend schemas, eliminating client-side tenant code forks, and inject white-label branding via W3C Design Tokens (DTCG).
+
+---
+
+## 1. The YAGNI Gate: Static Client Components vs. Server-Driven UI
+
+Server-Driven UI requires building and maintaining a JSON schema specification, schema versioning, validation, and multi-platform component interpreters. **Never build a Server-Driven UI when standard client-side components and modern web deployments solve the problem.**
+
+```mermaid
+flowchart TD
+    subgraph SDUIGate["Server-Driven UI YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Standard React/JSX components styled with Tailwind CSS<br/>• Instant web deployments via continuous delivery<br/>• Zero dynamic layout interpreters or backend schema JSONs"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Web-only SaaS dashboards, internal admin tools, or landing pages<br/>• Early-stage products iterating on UI layouts<br/>• Teams without multi-platform client parity requirements"]
+        B3["3. The Tipping Point (Graduation)<br/>• Native mobile apps (iOS/Android) where app store review cycles delay urgent UI/flow mutations<br/>• Multi-tenant white-label products where customers dynamically construct custom form layouts<br/>• Cross-platform parity: 1 backend drives layout across Web, iOS SwiftUI, and Android Jetpack Compose"]
+        B1 -->|Forbidden if web-only or early| B2
+        B1 -->|Triggered by multi-platform or white-label| B3
+    end
+```
+
+---
+
+## 2. Declarative Client-Agnostic SDUI Schema
+
+The backend provides a declarative UI layout schema describing fields, layouts, dynamic visibility rules (via Common Expression Language or JSON expressions), and allowed actions (`_actions`):
+
+```json
+{
+  "view": "OrderEdit",
+  "layout": "two-column",
+  "sections": [
+    {
+      "id": "general",
+      "title": "General Details",
+      "components": [
+        { "type": "TextInput", "id": "orderNumber", "label": "Order #", "readOnly": true },
+        { "type": "TextInput", "id": "custom_attributes.poNumber", "label": "PO Number", "required": true }
+      ]
+    },
+    {
+      "id": "tax",
+      "title": "Tax Exemption",
+      "visibleIf": "order.custom_attributes.isTaxExempt == true",
+      "components": [
+        { "type": "TextInput", "id": "custom_attributes.taxExemptionId", "label": "Tax ID", "required": true }
+      ]
+    }
+  ],
+  "_actions": [
+    { "action": "SUBMIT_FOR_APPROVAL", "label": "Submit Order", "method": "POST", "target": "/api/v1/orders/123/submit" }
+  ]
+}
+```
+
+---
+
+## 3. Multi-Platform Component Registries
+
+Frontend clients (Web, Mobile, Desktop) never contain hardcoded tenant branching. Each platform implements a local **Component Registry** mapping backend descriptors to native platform primitives:
+
+- **Web Clients**: Rendered dynamically via accessible primitives (Web Components, React, Vue, Svelte, or Solid).
+- **Mobile Clients**: Rendered natively via Flutter, iOS SwiftUI, or Android Jetpack Compose.
+- **Desktop Clients**: Rendered natively via Tauri or cross-platform toolkits.
+
+---
+
+## 4. Universal Design Tokens (W3C DTCG Standard)
+
+Manage tenant white-label branding and design systems via the **W3C Design Tokens Community Group (DTCG)** specification:
+
+```json
+{
+  "color": {
+    "brand": {
+      "primary": { "$value": "#1e40af", "$type": "color" },
+      "accent": { "$value": "#f59e0b", "$type": "color" }
+    }
+  },
+  "dimension": {
+    "radius": {
+      "base": { "$value": "6px", "$type": "dimension" }
+    }
+  }
+}
+```
+
+- **Universal Compilation**: Process tenant `tokens.json` files using **Style Dictionary** to compile dynamic themes at runtime for CSS Custom Properties (`--color-brand-primary`), Android XML / Compose, and iOS Swift tokens without code redeployments.