From f05e1c6d0529b8a9293cd113841081a407ecf1bb Mon Sep 17 00:00:00 2001 From: Firman Ramdhani <33869609+firmanramdhani@users.noreply.github.com> Date: Wed, 24 Jun 2026 13:53:48 +0700 Subject: [PATCH] docs: expand monorepo architectural documentation and add Git link to homepage --- apps/docs-dev/src/index.md | 3 ++ apps/docs-dev/src/overview.md | 80 +++++++++++++++++++++++++++++++++-- 2 files changed, 80 insertions(+), 3 deletions(-) diff --git a/apps/docs-dev/src/index.md b/apps/docs-dev/src/index.md index 5090758..93268af 100644 --- a/apps/docs-dev/src/index.md +++ b/apps/docs-dev/src/index.md @@ -11,6 +11,9 @@ hero: - theme: alt text: UI Components link: /packages/ui/ + - theme: alt + text: View on Git + link: https://git.eigen.co.id/eigen/fe-monorepo-template features: - title: Centralized Source of Truth details: All documentation for apps and packages is unified here. diff --git a/apps/docs-dev/src/overview.md b/apps/docs-dev/src/overview.md index 6146a4f..70f3124 100644 --- a/apps/docs-dev/src/overview.md +++ b/apps/docs-dev/src/overview.md @@ -31,25 +31,55 @@ The monorepo is organized into **Apps** (deployable applications) and **Packages ### 1. `apps/web` The main consumer-facing application. + * Imports business logic from `@repo/utils` * Uses shared UI components from `@repo/ui` -**Tech Stack**: React, Vite, TypeScript, Tailwind CSS +**Tech Stack**: + +* React +* Vite +* TypeScript +* Tailwind CSS ### 2. `apps/desktop` The **Electron desktop wrapper** that embeds `apps/web` for native desktop experiences. + * In **development**: loads the Vite dev server with full hot reload * In **production**: serves the static web build via a secure custom `app://` protocol * Configurable target app via `.env` (can wrap `apps/web`, `apps/docs-dev`, or any future app) -**Tech Stack**: Electron 33.x, electron-vite, electron-builder, electron-updater +**Tech Stack**: + +* Electron 33.x +* electron-vite +* electron-builder +* electron-updater + +**Key Capabilities**: + +| Feature | Description | +|---|---| +| ๐Ÿ–จ๏ธ Native Printing | Silent and direct printing via secure IPC bridge | +| ๐Ÿ”„ Auto-Updates | Background downloads via GitHub Releases (switchable to S3) | +| ๐Ÿ”’ Secure IPC Bridge | `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true` | +| ๐ŸŒ Custom Protocol | `app://` serves static files with SPA routing fallback to `index.html` | +| ๐Ÿ›ก๏ธ CORS Bypass | Transparent Origin header rewriting for cloud API calls | ### 3. `apps/landing` The **public promotional website** โ€” a standalone SPA for the company profile and marketing pages. + * Deployed independently to the web (e.g., Vercel) โ€” no interaction with Electron * Consumes shared UI components from `@repo/ui` and utilities from `@repo/utils` * Locked to port **3000** (`strictPort: true`) โ€” evacuated from the `517x` range to avoid `electron-vite` port collisions +**Tech Stack**: + +* React +* Vite +* TypeScript +* Tailwind CSS v4 + ### 4. `apps/docs-dev` An isolated environment for developing and documenting UI components. * Ensures components in `@repo/ui` are built and tested independently @@ -59,25 +89,69 @@ An isolated environment for developing and documenting UI components. ### 5. `packages/core-api` The **platform-agnostic API engine** for the monorepo. Provides an isolated HTTP client factory, a unified observability pipeline (Grafana Faro + OpenTelemetry), and a generic data services engine. +* Consumed by `apps/web`, `apps/landing`, and any future workspace +* Centralizes all `@grafana/faro-*` and `@opentelemetry/*` dependencies +* Provides plug-and-play telemetry via `initTelemetry()` + `faroAdapter` + +**Tech Stack**: + +* Axios (isolated instances, zero singleton pollution) +* Grafana Faro (RUM, Logs, Error tracking) +* OpenTelemetry (custom spans, distributed tracing) +* TypeScript (strict types, module augmentation) + +**Key Capabilities**: + +| Feature | Description | +|---|---| +| ๐Ÿญ HTTP Client Factory | `createHttpClient()` โ€” per-app isolated Axios instances with interceptor hooks | +| ๐Ÿ“ก Faro/Loki Baseline | Every request automatically pushes structured logs with `module.key` and `module.action` | +| ๐ŸŽฏ Custom Spans (Opt-In) | `telemetryContext.customSpanName` creates explicit OTel spans visible in Grafana Tempo | +| ๐Ÿ›ก๏ธ Error Normalization | `ApiError.fromAxiosError()` โ€” structured, serializable error codes for all failure modes | +| ๐Ÿ“ฆ Data Services Engine | `CommonRemoteDataServices` โ€” full CRUD + lifecycle operations with zero boilerplate | + ### 6. `packages/core-storage` The **Enterprise-grade storage engine** for the monorepo. Provides a unified, Promise-based interface for interacting with browser storage (`localStorage` and `IndexedDB`). Enforces strict type safety, prevents key collisions via a centralized registry, and automatically provides **AES encryption at rest** for sensitive payloads using `@repo/utils`. ### 7. `packages/core-i18n` The **Enterprise Internationalization Architecture** for the monorepo. + Provides a Hybrid Namespace Architecture combining a centralized i18n engine with decentralized, lazy-loaded feature dictionaries. Features strict TypeScript typings (including nested keys), optional backend synchronization with automatic error rollbacks, and a deep-merge mechanism for dynamic tenant-specific vocabulary overrides. +**Key Capabilities**: + +| Feature | Description | +|---|---| +| ๐ŸŒ Hybrid Namespaces | Centralized `common` corpus + lazy-loaded feature dictionaries. | +| ๐Ÿ›ก๏ธ Strict Typings | Native TS autocomplete for nested paths (e.g., `header.title`) via module augmentation. | +| ๐Ÿ”„ Safe Backend Sync | `changeLanguage` accepts a `syncCallback` with built-in rollback if the API fails. | +| ๐Ÿข Tenant Overrides | `applyTenantOverrides` performs a partial deep-merge to selectively override terminology. | + ### 8. `packages/core-events` The **decoupled Nervous System** for the monorepo. + Provides a highly performant, strictly typed Event Bus (Pub/Sub) powered by `mitt`. It allows independent modules to communicate seamlessly without tightly coupling their codebases or triggering expensive global React tree re-renders. +**Key Capabilities**: + +| Feature | Description | +|---|---| +| ๐Ÿงฉ Zero Coupling | Publishers and subscribers interact via blind events, eliminating direct module imports and circular dependencies. | +| โšก Extreme Performance | Enables targeted DOM updates for high-frequency data streams (e.g., WebSockets) without re-rendering parent components. | +| ๐Ÿงน Memory Safety | Native `useAppEvent` hook automatically unsubscribes on component unmount, preventing SPA memory leaks. | +| ๐Ÿ›ก๏ธ Strict Contracts | Centralized `events.registry.ts` enforces payload shapes via TypeScript, ensuring cross-module data safety. | + ### 9. `packages/utils` Shared business logic and reusable utility modules that can be consumed across multiple applications. Fully tested using Vitest. +This package is intended to hold non-UI, cross-cutting logic such as date/time handling, security helpers, and other common utilities. It is designed to be framework-agnostic, predictable, and easy to extend as the system evolves. + ### 10. `packages/ui` Shared UI component library (Buttons, Inputs, Cards, Layouts) with a comprehensive **Form UI Library**. + * Ensures consistent design across all applications -* Designed to be consumed by both web apps and docs +* Designed to be consumed by both web apps and Storybook * **Form UI Library**: 22 RHF-connected Mantine form components with Zod validation and i18n error translation, built via a `withRHF()` HOC factory with `useController` micro-subscriptions and `React.memo` optimization for ERP-scale forms ### 11. `packages/configs`