docs: enrich documentation with architectural foundations, component descriptions, and external library links across the codebase.
This commit is contained in:
Firman Ramdhani
@@ -1,5 +1,9 @@
|
||||
# Monorepo Architecture Overview
|
||||
|
||||
> **Architectural Foundation:** [Turborepo](https://turbo.build/repo) · [pnpm](https://pnpm.io/) · [Vite](https://vite.dev/) · [TypeScript](https://www.typescriptlang.org/)
|
||||
>
|
||||
> **Description:** Architectural overview of the monorepo, orchestrated by Turborepo with pnpm workspaces, housing React/Vite applications and shared TypeScript packages.
|
||||
|
||||
## 📂 Repository Structure
|
||||
|
||||
The monorepo is organized into **Apps** (deployable applications) and **Packages** (shared libraries).
|
||||
@@ -37,10 +41,10 @@ The main consumer-facing application.
|
||||
|
||||
**Tech Stack**:
|
||||
|
||||
* React
|
||||
* Vite
|
||||
* TypeScript
|
||||
* Tailwind CSS
|
||||
* [React](https://react.dev/)
|
||||
* [Vite](https://vite.dev/)
|
||||
* [TypeScript](https://www.typescriptlang.org/)
|
||||
* [Tailwind CSS](https://tailwindcss.com/)
|
||||
|
||||
### 2. `apps/desktop`
|
||||
The **Electron desktop wrapper** that embeds `apps/web` for native desktop experiences.
|
||||
@@ -51,10 +55,10 @@ The **Electron desktop wrapper** that embeds `apps/web` for native desktop exper
|
||||
|
||||
**Tech Stack**:
|
||||
|
||||
* Electron 33.x
|
||||
* electron-vite
|
||||
* electron-builder
|
||||
* electron-updater
|
||||
* [Electron](https://www.electronjs.org/) 33.x
|
||||
* [electron-vite](https://electron-vite.org/)
|
||||
* [electron-builder](https://www.electron.build/)
|
||||
* [electron-updater](https://www.npmjs.com/package/electron-updater)
|
||||
|
||||
**Key Capabilities**:
|
||||
|
||||
@@ -69,25 +73,25 @@ The **Electron desktop wrapper** that embeds `apps/web` for native desktop exper
|
||||
### 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
|
||||
* Deployed independently to the web (e.g., [Vercel](https://vercel.com/)) — 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
|
||||
* [React](https://react.dev/)
|
||||
* [Vite](https://vite.dev/)
|
||||
* [TypeScript](https://www.typescriptlang.org/)
|
||||
* [Tailwind CSS](https://tailwindcss.com/) v4
|
||||
|
||||
### 4. `apps/docs-dev`
|
||||
An isolated environment for developing and documenting UI components.
|
||||
* Ensures components in `@repo/ui` are built and tested independently
|
||||
* Acts as a living design system and playground
|
||||
* Built with **VitePress**
|
||||
* Built with **[VitePress](https://vitepress.dev/)**
|
||||
|
||||
### 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.
|
||||
The **platform-agnostic API engine** for the monorepo. Provides an isolated HTTP client factory, a unified observability pipeline ([Grafana Faro](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/faro-web-sdk/) + [OpenTelemetry](https://opentelemetry.io/)), and a generic data services engine.
|
||||
|
||||
* Consumed by `apps/web`, `apps/landing`, and any future workspace
|
||||
* Centralizes all `@grafana/faro-*` and `@opentelemetry/*` dependencies
|
||||
@@ -95,10 +99,10 @@ The **platform-agnostic API engine** for the monorepo. Provides an isolated HTTP
|
||||
|
||||
**Tech Stack**:
|
||||
|
||||
* Axios (isolated instances, zero singleton pollution)
|
||||
* Grafana Faro (RUM, Logs, Error tracking)
|
||||
* OpenTelemetry (custom spans, distributed tracing)
|
||||
* TypeScript (strict types, module augmentation)
|
||||
* [Axios](https://axios-http.com/) (isolated instances, zero singleton pollution)
|
||||
* [Grafana Faro](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/faro-web-sdk/) (RUM, Logs, Error tracking)
|
||||
* [OpenTelemetry](https://opentelemetry.io/) (custom spans, distributed tracing)
|
||||
* [TypeScript](https://www.typescriptlang.org/) (strict types, module augmentation)
|
||||
|
||||
**Key Capabilities**:
|
||||
|
||||
@@ -131,7 +135,7 @@ Provides a Hybrid Namespace Architecture combining a centralized i18n engine wit
|
||||
### 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.
|
||||
Provides a highly performant, strictly typed Event Bus (Pub/Sub) powered by [`mitt`](https://www.npmjs.com/package/mitt). It allows independent modules to communicate seamlessly without tightly coupling their codebases or triggering expensive global React tree re-renders.
|
||||
|
||||
**Key Capabilities**:
|
||||
|
||||
@@ -143,7 +147,7 @@ Provides a highly performant, strictly typed Event Bus (Pub/Sub) powered by `mit
|
||||
| 🛡️ 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.
|
||||
Shared business logic and reusable utility modules that can be consumed across multiple applications. Fully tested using [Vitest](https://vitest.dev/).
|
||||
|
||||
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.
|
||||
|
||||
@@ -152,17 +156,17 @@ Shared UI component library (Buttons, Inputs, Cards, Layouts) with a comprehensi
|
||||
|
||||
* Ensures consistent design across all applications
|
||||
* 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
|
||||
* **Form UI Library**: 22 RHF-connected [Mantine](https://mantine.dev/) form components with [Zod](https://zod.dev/) 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`
|
||||
Single source of truth for tooling configuration.
|
||||
* **eslint-config**: Shared ESLint rules
|
||||
* **eslint-config**: Shared [ESLint](https://eslint.org/) rules
|
||||
* **typescript-config**: Shared `tsconfig.json` base configurations
|
||||
|
||||
## ⚙️ Configuration & Environment
|
||||
|
||||
### Turborepo Caching
|
||||
This repository uses **Turborepo caching** for builds, tests, and other artifacts.
|
||||
This repository uses **[Turborepo](https://turbo.build/repo) caching** for builds, tests, and other artifacts.
|
||||
To fully clean the workspace (dependencies, build outputs, and Turbo cache):
|
||||
```bash
|
||||
rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist out **/*/out web-dist **/*/web-dist release **/*/release
|
||||
|
||||
Reference in New Issue
Block a user