docs: expand monorepo architectural documentation and add Git link to homepage
This commit is contained in:
Firman Ramdhani
@@ -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.
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user