# Frontend Monorepo Template

![Turborepo](https://img.shields.io/badge/Turborepo-2.7.2-red?style=flat\&logo=turborepo)
![pnpm](https://img.shields.io/badge/pnpm-8.15.6-orange?style=flat\&logo=pnpm)
![Node.js](https://img.shields.io/badge/Node.js-v24.11.1-green?style=flat\&logo=nodedotjs)
![Vite](https://img.shields.io/badge/Vite-Bundler-blue?style=flat\&logo=vite)
![React](https://img.shields.io/badge/React-Framework-cyan?style=flat\&logo=react)
![Electron](https://img.shields.io/badge/Electron-33.x-47848F?style=flat\&logo=electron)
![TypeScript](https://img.shields.io/badge/TypeScript-Language-blue?style=flat\&logo=typescript)
![Vitest](https://img.shields.io/badge/Vitest-Testing-green?style=flat\&logo=vitest)

A **scalable, enterprise-ready Web & Desktop monorepo** built with **Turborepo**, **pnpm**, **Vite**, and **Electron**.
This repository is designed for long-term maintainability, featuring:

* Shared logic and UI libraries
* Centralized tooling configuration
* Turbo-powered task orchestration and caching
* Native desktop distribution with auto-updates
* Dedicated documentation & component playground using Storybook

---

## 📂 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 (Storybook)
│
├── 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
```

---

## 🚀 Getting Started

### Prerequisites

Ensure your local environment matches the following versions to avoid compatibility issues:

* **Node.js**: `v20+` (tested with `v24.11.1`) — required for the `--import tsx` flag used by the desktop prebuild script
* **pnpm**: `v8.15.6`
  (Enforced via the `packageManager` field in `package.json`)

### Installation

Install all dependencies from the **root directory**:

```bash
pnpm install
```

---

## 🛠 Usage & Scripts

This repository uses **Turborepo** to orchestrate tasks efficiently. All commands are executed from the root.

### Development

| Command              | Description                                                                        |
| -------------------- | ---------------------------------------------------------------------------------- |
| `pnpm dev`           | Start **all applications** (`web` and `docs-dev`) in parallel                      |
| `pnpm dev:web`       | Start only the **Main Web App** (strictly at `http://localhost:5173`)               |
| `pnpm dev:landing`   | Start the **Public Landing App** (strictly at `http://localhost:3000`)              |
| `pnpm dev:docs-dev`  | Start **Storybook** for UI development (strictly at `http://localhost:6006`)        |
| `pnpm dev:desktop`   | Start the **Web App + Electron** in parallel for desktop development               |

> [!NOTE]
> **Port Topology**: `electron-vite` dynamically allocates a background port (usually `5174`) for its internal renderer shell during `pnpm dev:desktop`. We strictly isolate `web` (`5173`) and `landing` (`3000`) onto separate port ranges to prevent race conditions during parallel execution.

### Building & Quality

| Command               | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `pnpm build`          | Build all apps and packages using Turbo cache           |
| `pnpm build:web`      | Build only the web application                          |
| `pnpm build:landing`  | Build only the landing page                             |
| `pnpm build:docs-dev` | Build only the docs-dev application                     |
| `pnpm build:desktop`  | Build the web app, then compile the Electron app        |
| `pnpm test`           | Run unit tests (Vitest) across all packages             |
| `pnpm lint`           | Run ESLint across the workspace                         |
| `pnpm format`         | Format code using Prettier                              |

### 🚀 Desktop Packaging & Distribution

To package the application into a production-ready installer, use the following commands from the **root directory**:

| Command                | Platform    | Output Artifact                            |
| ---------------------- | ----------- | ------------------------------------------ |
| `pnpm package:desktop` | Current OS  | Detects host OS and builds accordingly     |
| `pnpm package:mac`     | macOS       | `.dmg` and `.zip` (supports x64 & arm64)   |
| `pnpm package:win`     | Windows     | `.exe` (NSIS Installer)                    |
| `pnpm package:linux`   | Linux       | `.AppImage`                                |

> [!IMPORTANT]
> **Build Sequence**: All `package:*` commands execute the following pipeline automatically:
>
> 1. **`turbo run build --filter=web`** — Compiles the React SPA into `apps/web/dist/`.
> 2. **`prebuild` hook** — Runs `node --import tsx scripts/copy-web-dist.ts`, which copies `apps/web/dist/` → `apps/desktop/web-dist/`.
> 3. **`electron-builder`** — Bundles `web-dist/` into the packaged app via the `files` and `extraResources` blocks in `electron-builder.yml`.
>
> You do not need to run these steps manually — they are chained via npm scripts.

> [!WARNING]
> **macOS Code Signing**: To build a distributable macOS app with Auto-Update support, you **must** have an Apple Developer Certificate and provide `CSC_LINK` and `CSC_KEY_PASSWORD` in your environment. Without code signing, macOS Gatekeeper will block the app and auto-updates will fail. See [AUTO_UPDATER.md](apps/desktop/docs/AUTO_UPDATER.md) for details.

> [!NOTE]
> **Cross-Compilation**: It is highly recommended to build for Windows on a Windows machine and for macOS on a Mac. Cross-compilation (e.g., building `.dmg` on Linux) may fail due to platform-specific toolchain dependencies. Use a CI matrix strategy (e.g., GitHub Actions with `runs-on: [macos-latest, windows-latest, ubuntu-latest]`) for multi-platform releases.


---

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

**Desktop Documentation**:

| Document | Contents |
|---|---|
| [CONFIGURATION.md](apps/desktop/docs/CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback |
| [AUTO_UPDATER.md](apps/desktop/docs/AUTO_UPDATER.md) | Release workflow, CI/CD variables, provider switching, code signing |
| [IPC_ARCHITECTURE.md](apps/desktop/docs/IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, extending native features |

---

### 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` (Storybook)

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

---

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

**Documentation**:

| Document | Contents |
|---|---|
| [README.md](packages/core-api/README.md) | Architecture, HTTP client setup, observability strategy, data services, app integration guide |

---

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

**Documentation**: [README.md](packages/core-storage/README.md)

---

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

**Documentation**: [README.md](packages/core-i18n/README.md)

---

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

**Documentation**: [README.md](packages/core-events/README.md)

---

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

* Ensures consistent design across all applications
* Designed to be consumed by both web apps and Storybook

---

### 11. `packages/configs`

Single source of truth for tooling configuration.

* **eslint-config**: Shared ESLint rules (React, libraries, Storybook)
* **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):

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

---

## 📝 License

This project is **private and proprietary**.