From ab0625d39366ceb70be9c3c0bbcee0101c38243b Mon Sep 17 00:00:00 2001 From: Firman Ramdhani <33869609+firmanramdhani@users.noreply.github.com> Date: Fri, 29 May 2026 16:29:46 +0700 Subject: [PATCH] feat: enhance architecture diagrams in README for core-api and core-i18n with improved styling and clarity --- packages/core-api/README.md | 64 +++++++++++++++++++++--------------- packages/core-i18n/README.md | 51 ++++++++++++++-------------- 2 files changed, 64 insertions(+), 51 deletions(-) diff --git a/packages/core-api/README.md b/packages/core-api/README.md index 41f8b47..1dc2365 100644 --- a/packages/core-api/README.md +++ b/packages/core-api/README.md @@ -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) diff --git a/packages/core-i18n/README.md b/packages/core-i18n/README.md index 2495a15..42f1fef 100644 --- a/packages/core-i18n/README.md +++ b/packages/core-i18n/README.md @@ -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
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 ``` ---