feat: enhance architecture diagrams in README for core-api and core-i18n with improved styling and clarity

2026-05-29 16:29:46 +07:00
parent d3eb242ebe
commit ab0625d393
2 changed files with 64 additions and 51 deletions
@@ -9,13 +9,20 @@ The platform-agnostic API engine for the monorepo. Provides an isolated HTTP cli
 ---

 ## Architecture Overview
-
 ```mermaid
 graph TD
+    %% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
+    classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
+    classDef coreEngine fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
+    classDef dataService fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
+    classDef observability fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
+    classDef errorNode fill:#f43f5e,stroke:#be123c,stroke-width:2px,color:#ffffff
+
+    %% ─── Subgraphs ───
    subgraph Apps ["apps/* (App Autonomy)"]
-        WEB[apps/web]
-        LAND[apps/landing]
-        DESK[apps/desktop]
+        WEB([apps/web])
+        LAND([apps/landing])
+        DESK([apps/desktop])
    end

    subgraph Core ["@repo/core-api (Engine)"]
@@ -34,28 +41,31 @@ graph TD
        end
    end

-    WEB & LAND & DESK -->|instantiates| FACTORY
-    WEB & LAND & DESK -->|extends| COMMON
-    COMMON -->|executes via| FACTORY
+    %% ─── Flow & Relationships ───
+    WEB & LAND & DESK ===>|instantiates| FACTORY
+    WEB & LAND & DESK ===>|extends| COMMON
+    
+    COMMON --->|executes via| FACTORY
    FACTORY -.->|reports via| FARO
    FACTORY -.->|throws| API_ERR

-    %% Styling Subgraphs (Backgrounds)
-    style Apps fill:#e7f5ff,stroke:#74c0fc,stroke-width:2px,color:#1864ab
-    style Core fill:#f8f9fa,stroke:#ced4da,stroke-width:2px,color:#495057
+    %% ─── Apply Styles ───
+    class WEB,LAND,DESK appEntity;
+    class FACTORY coreEngine;
+    class BASE,COMMON dataService;
+    class FARO observability;
+    class API_ERR errorNode;
+
+    %% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
+    style Apps fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
+    style Core fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
    
-    %% Styling Nodes (Apps - Blue)
-    style WEB fill:#339af0,stroke:#1864ab,color:#fff
-    style LAND fill:#339af0,stroke:#1864ab,color:#fff
-    style DESK fill:#339af0,stroke:#1864ab,color:#fff
-    
-    %% Styling Nodes (Core Modules)
-    style FACTORY fill:#845ef7,stroke:#5f3dc4,color:#fff
-    style FARO fill:#fd7e14,stroke:#d9480f,color:#fff
-    style BASE fill:#20c997,stroke:#089981,color:#fff
-    style COMMON fill:#20c997,stroke:#089981,color:#fff
-    style API_ERR fill:#fa5252,stroke:#c92a2a,color:#fff
-```
+    %% Nested subgraphs also need transparent backgrounds to prevent glaring white boxes in dark mode
+    style HTTP fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
+    style OBS fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
+    style DATA fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
+    style ERRORS fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
+  ```

 ### Data Flow Lifecycle

@@ -65,24 +75,26 @@ Every HTTP request flows through this precise interceptor pipeline:
 sequenceDiagram
    autonumber

-    box #e7f5ff App Layer (Consumers)
+    %% ─── Dark-Mode Friendly RGBA Boxes ───
+    box rgba(59, 130, 246, 0.1) App Layer (Consumers)
        participant C as UI Component
    end

-    box #f8f9fa Core Engine (@repo/core-api)
+    box rgba(148, 163, 184, 0.1) Core Engine (@repo/core-api)
        participant S as Data Service
        participant H as HTTP Client
        participant F as Faro Adapter
    end

-    box #e7f5ff App Logic (IoC)
+    box rgba(16, 185, 129, 0.1) App Logic (IoC)
        participant A as App Hooks
    end

-    box #fff5f5 External
+    box rgba(245, 158, 11, 0.1) External
        participant N as Network
    end

+    %% ─── Execution Flow ───
    C->>S: getMany()
    S->>H: request()
    H->>F: onRequestStart() (Log + Span)
@@ -16,49 +16,50 @@ This architecture strictly adheres to **Inversion of Control (IoC)**. The core e

 ```mermaid
 graph TD
+    %% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
+    classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
+    classDef coreEngine fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
+    classDef dataStore fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
+    classDef externalAPI fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
+
+    %% ─── Subgraphs ───
    subgraph Apps ["apps/* (App Autonomy)"]
-        UI[React Components]
-        DICT[Feature Dictionaries<br/>e.g., booking.json]
+        UI([React Components])
+        DICT[[Feature Dictionaries: booking.json]]
    end

    subgraph Core ["@repo/core-i18n (Engine)"]
-        I18N((i18next Instance))
+        I18N[i18next Instance]
        STORE[(core-storage)]
        COMMON[Common Vocabulary]
    end

    subgraph Backend ["Backend API (External)"]
-        SYNC[Language Sync Endpoint]
-        TENANT[Tenant Config Endpoint]
+        SYNC([Language Sync Endpoint])
+        TENANT([Tenant Config Endpoint])
    end

-    UI -->|uses useTranslation| I18N
+    %% ─── Flow & Relationships ───
+    UI ===>|uses useTranslation| I18N
    DICT -.->|lazy loads| I18N
-    COMMON -->|preloads| I18N
-    I18N <-->|reads/persists| STORE
+    COMMON --->|preloads| I18N
+    I18N <===>|reads / persists| STORE
    
-    I18N -->|changeLanguage sync| SYNC
+    I18N --->|changeLanguage sync| SYNC
    SYNC -.->|fails? rollback| I18N
    
    TENANT -.->|applyTenantOverrides| I18N

-    %% Styling Subgraphs (Backgrounds)
-    style Apps fill:#e7f5ff,stroke:#74c0fc,stroke-width:2px,color:#1864ab
-    style Core fill:#f8f9fa,stroke:#ced4da,stroke-width:2px,color:#495057
-    style Backend fill:#fff4e6,stroke:#ffd8a8,stroke-width:2px,color:#d9480f
+    %% ─── Apply Styles ───
+    class UI,DICT appEntity;
+    class I18N coreEngine;
+    class STORE,COMMON dataStore;
+    class SYNC,TENANT externalAPI;

-    %% Styling App Nodes (Blue)
-    style UI fill:#339af0,stroke:#1864ab,color:#fff
-    style DICT fill:#339af0,stroke:#1864ab,color:#fff
-
-    %% Styling Core Nodes (Purple Engine, Green Storage/Data)
-    style I18N fill:#845ef7,stroke:#5f3dc4,color:#fff
-    style STORE fill:#20c997,stroke:#089981,color:#fff
-    style COMMON fill:#20c997,stroke:#089981,color:#fff
-
-    %% Styling Backend Nodes (Orange/Network)
-    style SYNC fill:#fd7e14,stroke:#d9480f,color:#fff
-    style TENANT fill:#fd7e14,stroke:#d9480f,color:#fff
+    %% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
+    style Apps fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
+    style Core fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
+    style Backend fill:transparent,stroke:#f59e0b,stroke-width:2px,stroke-dasharray: 5 5
 ```

 ---