trackgo-fe/apps/docs-dev/src/overview.md

Monorepo Architecture Overview

Architectural Foundation: Turborepo · pnpm · Vite · TypeScript

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).

.
├── apps/
│   ├── web/              # Main React Application (Vite + TypeScript)
│   ├── landing/          # Public Promotional SPA (Vite + TypeScript)
│   ├── desktop/          # Electron Desktop Wrapper (electron-vite)
│   └── docs-dev/         # Component Documentation & Playground (VitePress)
│
├── packages/
│   ├── core-api/         # Shared HTTP Client, Observability & Data Services Engine
│   ├── core-storage/     # Enterprise Storage Engine (IndexedDB/localStorage + Encryption)
│   ├── core-i18n/        # Enterprise Internationalization Architecture
│   ├── ui/               # Shared UI Component Library
│   ├── utils/            # Shared Utilities (Date, Encryption, Core Logic, etc)
│   └── configs/          # Shared Tooling Configurations
│       ├── eslint/       # Shared ESLint rules
│       └── typescript/   # Shared TypeScript (tsconfig) bases
│
├── package.json          # Root scripts and dependencies
├── pnpm-workspace.yaml   # pnpm workspace definition
└── turbo.json            # Turborepo pipeline configuration

📦 Packages Overview

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

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

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
• Acts as a living design system and playground
• Built with VitePress

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 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

Single source of truth for tooling configuration.

• eslint-config: Shared ESLint rules
• typescript-config: Shared tsconfig.json base configurations

⚙️ Configuration & Environment

Turborepo Caching

This repository uses Turborepo caching for builds, tests, and other artifacts. To fully clean the workspace (dependencies, build outputs, and Turbo cache):

rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist out **/*/out web-dist **/*/web-dist release **/*/release