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

```text
.
├── 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](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.

- 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](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**:

| 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](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](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](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](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
- Provides plug-and-play telemetry via `initTelemetry()` + `faroAdapter`

**Tech Stack**:

- [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**:

| 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`](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**:

| 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](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.

### 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](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](https://eslint.org/) rules
- **typescript-config**: Shared `tsconfig.json` base configurations

## ⚙️ Configuration & Environment

### Turborepo Caching

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