eigen/trackgo-fe
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: enrich documentation with architectural foundations, component descriptions, and external library links across the codebase.

Browse Source
This commit is contained in:
Firman Ramdhani
2026-06-24 17:43:55 +07:00
parent 3d56eed2b8
commit cccc2c40fc
13 changed files with 112 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs-dev/src/packages/core-api/index.md
+8 -5
View File
@@ -1,7 +1,10 @@
# Enterprise API Engine (`@repo/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.
> **Architectural Foundation:** [Axios](https://axios-http.com/) · [Grafana Faro](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/faro-web-sdk/) · [OpenTelemetry](https://opentelemetry.io/)
>
> **Description:** Platform-agnostic API engine providing isolated Axios HTTP client factories, a Grafana Faro + OpenTelemetry observability pipeline, and a generic CRUD data services layer.
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.
**This package enforces App Autonomy (IoC).** The core provides the engine and interceptor pipelines, but the consuming applications (`apps/web`, `apps/landing`) inject their own specific configurations, authentication tokens, and error handling behaviors.
@@ -122,7 +125,7 @@ sequenceDiagram
### `createHttpClient(config, hooks?)`
Creates an **isolated** Axios instance. Each app receives its own interceptor chain — no globals are shared or mutated.
Creates an **isolated** [Axios](https://axios-http.com/) instance. Each app receives its own interceptor chain — no globals are shared or mutated.
```typescript
import { createHttpClient } from '@repo/core-api/http-client';
@@ -179,7 +182,7 @@ The observability layer operates in two complementary modes:
| Mode | Activation | What it does |
|---|---|---|
| **Baseline** (always on) | Automatic | Pushes structured logs to Faro/Loki on every request with `module.key`, `module.action`, HTTP method, and URL |
| **Custom Span** (opt-in) | Via `telemetryContext.customSpanName` | Creates an explicit OTel span with custom tags, visible in Grafana Tempo |
| **Custom Span** (opt-in) | Via `telemetryContext.customSpanName` | Creates an explicit OTel span with custom tags, visible in [Grafana Tempo](https://grafana.com/oss/tempo/) |
> [!NOTE]
> `trace.getActiveSpan()` returns `undefined` inside Axios interceptors due to browser XHR/Fetch lifecycle race conditions with Faro's `TracingInstrumentation`. The adapter does **not** attempt to enrich auto-instrumented spans. HTTP span capture is handled entirely by `TracingInstrumentation` auto-instrumentation.
@@ -221,7 +224,7 @@ Every request dispatched through `BaseRemoteDataServices` automatically attaches
| `ex-module-key` | `DataServicesConfig.moduleKey` | Identifies the business module (e.g., `BOOKING`) |
| `ex-module-action` | `RequestDescriptor.action` | Identifies the operation (e.g., `READ`, `CREATE`) |
These headers are extracted by the `faroAdapter` and included in all Faro `pushLog`, `pushError`, and `pushEvent` calls as top-level context — making them directly queryable in **LogQL (Loki)**.
These headers are extracted by the `faroAdapter` and included in all Faro `pushLog`, `pushError`, and `pushEvent` calls as top-level context — making them directly queryable in **LogQL ([Loki](https://grafana.com/oss/loki/))**.
### Span Safety Guarantees
apps/docs-dev/src/packages/core-events/index.md
+5 -2
View File
@@ -1,6 +1,9 @@
# Event Bus (`@repo/core-events`)
> **Architectural Foundation:** [mitt](https://www.npmjs.com/package/mitt)
>
> **Description:** Strictly-typed global event bus powered by mitt, enabling decoupled pub/sub communication across React components with automatic memory-safe lifecycle cleanup.
The Global Pub/Sub & Hardware Integration Blueprint.
> This module provides a strictly-typed, global event bus for the monorepo ecosystem. It decouples cross-component communication and manages real-time hardware signals (such as printers and POS peripherals), ensuring a reactive and memory-safe architecture across all applications.
@@ -9,7 +12,7 @@ The Global Pub/Sub & Hardware Integration Blueprint.
## 🧠 System Overview
`@repo/core-events` is the **decoupled Nervous System** of the ERP. It provides a highly performant, strictly-typed Event Bus powered by `mitt` and custom React hooks.
`@repo/core-events` is the **decoupled Nervous System** of the ERP. It provides a highly performant, strictly-typed Event Bus powered by [`mitt`](https://www.npmjs.com/package/mitt) and custom [React](https://react.dev/) hooks.
**This package is a pure tool.** It ships zero application-specific events. Each consuming app (`apps/web`, `apps/desktop`, etc.) registers its own events autonomously using **TypeScript Declaration Merging** — the exact same Inversion of Control (IoC) pattern utilized by our `@repo/core-api` factory and `@repo/core-storage` engine.
apps/docs-dev/src/packages/core-i18n/index.md
+4 -1
View File
@@ -1,6 +1,9 @@
# i18n Architecture (`@repo/core-i18n`)
> **Architectural Foundation:** [i18next](https://www.i18next.com/) · [react-i18next](https://react.i18next.com/)
>
> **Description:** Hybrid namespace internationalization engine built on i18next, providing centralized common vocabularies with lazy-loaded feature dictionaries, tenant overrides, and backend sync with automatic rollback.
A highly decoupled, type-safe internationalization engine for the monorepo.
It uses a **Hybrid Namespace Strategy**:
apps/docs-dev/src/packages/core-storage/index.md
+7 -4
View File
@@ -1,14 +1,17 @@
# Storage Engine (`@repo/core-storage`)
> **Architectural Foundation:** [PouchDB](https://pouchdb.com/) · [CouchDB](https://couchdb.apache.org/) · [IndexedDB API (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
>
> **Description:** Enterprise storage engine providing AES-encrypted LocalStorage, strict-gatekeeper IndexedDB, and offline-first PouchDB with bi-directional CouchDB cloud synchronization.
`@repo/core-storage` is the **Enterprise-grade, multi-tool storage engine** for the Eigen Monorepo.
It provides a unified set of strictly-typed, secure, and fault-tolerant storage mechanisms tailored for React applications. It enforces strict **Inversion of Control (IoC)**—the core engine knows absolutely nothing about your application's business domains; instead, the consuming apps inject their own configurations and types.
This package provides three primary storage solutions:
1. **Secure Local Storage** (Strict Key-Gatekeeping & AES encryption)
2. **Secure IndexedDB** (For larger key-value payloads)
3. **Offline-First PouchDB** (For document-oriented, bi-directional sync data)
2. **Secure [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)** (For larger key-value payloads)
3. **Offline-First [PouchDB](https://pouchdb.com/)** (For document-oriented, bi-directional sync data)
---
@@ -113,7 +116,7 @@ const theme = await appStorage.getItem('THEME'); // Plaintext on disk
## 🔄 Offline-First Document Storage (PouchDB & CouchDB)
For complex, document-oriented data that requires fault-tolerance, offline support, and bi-directional cloud synchronization, we use the `PouchDatabaseManager`.
For complex, document-oriented data that requires fault-tolerance, offline support, and bi-directional cloud synchronization, we use the `PouchDatabaseManager`. This layer is powered by [PouchDB](https://pouchdb.com/) syncing to [CouchDB](https://couchdb.apache.org/).
### Architecture
apps/docs-dev/src/packages/ui/CORE-APP-SHELL.md
+5 -1
View File
@@ -4,8 +4,12 @@ outline: [2, 3]
# Core App Shell — Layout Engine
> **Architectural Foundation:** [Mantine AppShell](https://mantine.dev/core/app-shell/) · [@mantine/hooks](https://mantine.dev/hooks/package/)
>
> **Description:** Configuration-driven layout engine wrapping Mantine's AppShell, providing three layout variants (header-first, sidebar-first, top-nav), double sidebar support, responsive mobile drawers, and state persistence via Context API.
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/components`
> **Dependencies**: React 18+, Mantine v8 (`AppShell`), `@mantine/hooks`
> **Dependencies**: React 18+, [Mantine v8](https://mantine.dev/) (`AppShell`), [`@mantine/hooks`](https://mantine.dev/hooks/package/)
---
apps/docs-dev/src/packages/ui/FORM-COMPONENTS.md
+6 -2
View File
@@ -4,8 +4,12 @@ outline: [2, 3]
# Form UI Library
> **Architectural Foundation:** [React Hook Form v7](https://react-hook-form.com/) · [Zod v3](https://zod.dev/) · [Mantine v8](https://mantine.dev/) · [@hookform/resolvers](https://www.npmjs.com/package/@hookform/resolvers) · [@mantine/tiptap](https://mantine.dev/x/tiptap/)
>
> **Description:** 22 pre-built form field components generated via a withRHF() HOC factory, integrating Mantine inputs with React Hook Form micro-subscriptions, Zod validation, and i18n error translation for ERP-scale performance.
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/form`
> **Dependencies**: React Hook Form v7, Zod v3, Mantine v8, `@repo/core-i18n`
> **Dependencies**: [React Hook Form](https://react-hook-form.com/) v7, [Zod](https://zod.dev/) v3, [Mantine](https://mantine.dev/) v8, `@repo/core-i18n`
---
@@ -898,7 +902,7 @@ export const FieldDatePicker = withRHF<DatePickerInputProps>(
| `FieldRichTextEditor` | `@mantine/tiptap` | `string` (HTML) |
### Rich Text Editor (TipTap)
The `FieldRichTextEditor` component integrates `@mantine/tiptap` directly with React Hook Form. It safely stores the Editor's HTML output directly into the RHF state as a `string`. Because TipTap is an uncontrolled editor natively, this field uses a specialized `useController` wrapper that automatically syncs bidirectional updates (e.g., calling `editor.commands.setContent(field.value)` when the form is reset or async default values arrive).
The `FieldRichTextEditor` component integrates [`@mantine/tiptap`](https://mantine.dev/x/tiptap/) directly with React Hook Form. It safely stores the Editor's HTML output directly into the RHF state as a `string`. Because TipTap is an uncontrolled editor natively, this field uses a specialized `useController` wrapper that automatically syncs bidirectional updates (e.g., calling `editor.commands.setContent(field.value)` when the form is reset or async default values arrive).
---
apps/docs-dev/src/packages/ui/index.md
+9 -5
View File
@@ -1,14 +1,18 @@
# @repo/ui — Shared UI Component Library
> **Architectural Foundation:** [Mantine v8](https://mantine.dev/) · [React Hook Form v7](https://react-hook-form.com/) · [Zod v3](https://zod.dev/) · [Tailwind CSS v4](https://tailwindcss.com/)
>
> **Description:** Shared UI component library providing Mantine-based design primitives, a ThemeProvider with density modes, and a 22-component Form UI Library with RHF + Zod validation and i18n error translation.
The centralized UI component library for the monorepo. Provides consistent design primitives, system pages, and **a comprehensive Form UI Library** for building enterprise-grade forms.
## Features
- **Mantine v8** components re-exported with unified theming
- **[Mantine v8](https://mantine.dev/)** components re-exported with unified theming
- **ThemeProvider** with dark/light mode, brand colors, and density modes (compact/standard)
- **Design tokens** — Colors, typography, radius, spacing, shadows mapped between Mantine and Tailwind
- **System pages** — Pre-built 404, 403, Maintenance, and Coming Soon pages
- **Form UI Library** — 22 RHF-connected Mantine form components with Zod validation and i18n error translation
- **Form UI Library** — 22 RHF-connected Mantine form components with [Zod](https://zod.dev/) validation and i18n error translation
## Exports
@@ -74,7 +78,7 @@ function UserForm() {
## Dependencies
- `@mantine/core` v8, `@mantine/hooks` v8
- `react-hook-form` v7, `@hookform/resolvers` v5, `zod` v3
- [`@mantine/core`](https://mantine.dev/) v8, [`@mantine/hooks`](https://mantine.dev/hooks/package/) v8
- [`react-hook-form`](https://react-hook-form.com/) v7, [`@hookform/resolvers`](https://www.npmjs.com/package/@hookform/resolvers) v5, [`zod`](https://zod.dev/) v3
- `@repo/core-i18n` (workspace)
- `tailwindcss` v4, `tailwind-variants`, `tailwind-merge`
- [`tailwindcss`](https://tailwindcss.com/) v4, [`tailwind-variants`](https://www.tailwind-variants.org/), [`tailwind-merge`](https://www.npmjs.com/package/tailwind-merge)`