refactor: migrate docs-dev from storybook to vitepress config and update devcontainer configuration
This commit is contained in:
Firman Ramdhani
@@ -14,14 +14,19 @@
|
|||||||
},
|
},
|
||||||
|
|
||||||
// ─── Port Topology ──────────────────────────────────────────────────────────
|
// ─── Port Topology ──────────────────────────────────────────────────────────
|
||||||
// 6006: Storybook (Docs)
|
// 6060: VitePress Docs (Development)
|
||||||
|
// 4173: VitePress Docs (Preview)
|
||||||
// 5173: Web App (Must be strictly 5173 for Electron IPC compatibility)
|
// 5173: Web App (Must be strictly 5173 for Electron IPC compatibility)
|
||||||
// 3000: Landing App (Isolated from Vite's default 517x blast radius)
|
// 3000: Landing App (Isolated from Vite's default 517x blast radius)
|
||||||
"forwardPorts": [6006, 5173, 3000],
|
"forwardPorts": [6060, 4173, 5173, 3000],
|
||||||
|
|
||||||
"portsAttributes": {
|
"portsAttributes": {
|
||||||
"6006": {
|
"6060": {
|
||||||
"label": "Storybook",
|
"label": "VitePress Docs",
|
||||||
|
"onAutoForward": "notify"
|
||||||
|
},
|
||||||
|
"4173": {
|
||||||
|
"label": "VitePress Preview",
|
||||||
"onAutoForward": "notify"
|
"onAutoForward": "notify"
|
||||||
},
|
},
|
||||||
"5173": {
|
"5173": {
|
||||||
|
|||||||
+5
-1
@@ -43,4 +43,8 @@ release/
|
|||||||
web-dist/
|
web-dist/
|
||||||
|
|
||||||
# Legacy Code (if applicable)
|
# Legacy Code (if applicable)
|
||||||
legacy/
|
legacy/
|
||||||
|
|
||||||
|
# VitePress
|
||||||
|
**/.vitepress/cache/
|
||||||
|
**/.vitepress/dist/
|
||||||
@@ -10,324 +10,31 @@
|
|||||||
|
|
||||||
|
|
||||||
A **scalable, enterprise-ready Web & Desktop monorepo** built with **Turborepo**, **pnpm**, **Vite**, and **Electron**.
|
A **scalable, enterprise-ready Web & Desktop monorepo** built with **Turborepo**, **pnpm**, **Vite**, and **Electron**.
|
||||||
This repository is designed for long-term maintainability, featuring:
|
This repository is designed for long-term maintainability, featuring shared logic and UI libraries, centralized tooling configuration, turbo-powered task orchestration, and native desktop distribution with auto-updates.
|
||||||
|
|
||||||
* 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
|
## 🌍 Global Context
|
||||||
|
|
||||||
The monorepo is organized into **Apps** (deployable applications) and **Packages** (shared libraries).
|
This repository utilizes a monorepo architecture to seamlessly share core systems, business logic, and UI components across multiple distribution targets (Web, Desktop, and Landing Page).
|
||||||
|
|
||||||
```text
|
### Topology Overview
|
||||||
.
|
|
||||||
├── apps/
|
* **`apps/`**: Deployable applications (`web`, `desktop`, `landing`, `docs-dev`).
|
||||||
│ ├── web/ # Main React Application (Vite + TypeScript)
|
* **`packages/`**: Shared libraries and core engines (`core-api`, `core-storage`, `ui`, `utils`, `configs`, etc.).
|
||||||
│ ├── 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
|
## 📚 Single Source of Truth
|
||||||
|
|
||||||
### 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]
|
> [!IMPORTANT]
|
||||||
> **Build Sequence**: All `package:*` commands execute the following pipeline automatically:
|
> **Internal Documentation Hub**
|
||||||
>
|
> All documentation, installation guides, architectural deep-dives, and API references are hosted internally via our VitePress application.
|
||||||
> 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]
|
**To access the documentation and get started, run:**
|
||||||
> **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) 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
|
|
||||||
|
|
||||||
**Documentation**: [README.md](packages/ui/README.md) · [Form Components Guide](packages/ui/docs/FORM-COMPONENTS.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist out **/*/out web-dist **/*/web-dist release **/*/release
|
pnpm --filter docs-dev dev
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -1,29 +0,0 @@
|
|||||||
**Role:** You are a Staff Level React Engineer and Architect managing a highly scalable Enterprise ERP monorepo.
|
|
||||||
|
|
||||||
**Context:**
|
|
||||||
We have successfully established our Form UI library in `packages/ui/src/components/Form/fields` featuring 22 Mantine form components wrapped with React Hook Form (e.g., `FieldTextInput`, `FieldSelect`, `FieldColorPicker`, etc.). We also have a Zod validation layer at `packages/ui/src/validators` that uses JSON-stringified payloads for i18n translation.
|
|
||||||
We now need to build a showcase/demo page in the main web application to test and demonstrate these components in a real-world ERP form scenario.
|
|
||||||
|
|
||||||
**Pre-Execution Analysis (READ THESE FIRST):**
|
|
||||||
Before writing any code, you MUST read and analyze:
|
|
||||||
1. The component signatures and exports in `packages/ui/src/components/Form/index.ts`.
|
|
||||||
2. The Zod validator pattern in `packages/ui/src/validators` (specifically how the JSON i18n payloads are structured).
|
|
||||||
3. The existing layout and routing patterns in `apps/web/src/apps/showcase/showcase-view.tsx` to understand how to correctly inject and mount new showcase features.
|
|
||||||
|
|
||||||
**Task Requirements:**
|
|
||||||
|
|
||||||
**Phase 1: Create the Form Showcase Component**
|
|
||||||
1. Create a new comprehensive demo component inside `apps/web/src/apps/showcase/example/features/`. Follow the existing file naming convention found in that directory.
|
|
||||||
2. The component should implement a realistic ERP form (e.g., Textile Production Order, Inventory Bulk Update, or User Registration) using `useForm`, `zodResolver`, and a custom Zod schema.
|
|
||||||
3. The Zod schema MUST utilize the JSON-stringified i18n message pattern for validation errors.
|
|
||||||
4. Utilize a diverse set of our generated UI components (text input, select, number input, color input/picker, etc.) to prove they function correctly in a unified form.
|
|
||||||
5. Include a visual output panel (e.g., using Mantine's `Code` or `Pre` component) that displays the validated JSON payload upon successful submission.
|
|
||||||
|
|
||||||
**Phase 2: Connect to Showcase View**
|
|
||||||
1. Update `apps/web/src/apps/showcase/showcase-view.tsx` to import and render the newly created Form Showcase component.
|
|
||||||
2. Integrate it seamlessly into the existing UI layout of the showcase view (e.g., adding a new Tab, Accordion, or Section dedicated to the Form UI & Validation Layer).
|
|
||||||
|
|
||||||
**Execution Rules:**
|
|
||||||
- Do not rely on hardcoded assumptions. Let your code be guided completely by the patterns, styles, and typings you discover during the Pre-Execution Analysis.
|
|
||||||
- Ensure all TypeScript typings are strict.
|
|
||||||
- Output the newly created files and the modified files cleanly.
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
import { dirname, join, resolve } from 'path';
|
|
||||||
|
|
||||||
function getAbsolutePath(value) {
|
|
||||||
return dirname(require.resolve(join(value, 'package.json')));
|
|
||||||
}
|
|
||||||
|
|
||||||
const config = {
|
|
||||||
stories: ['../stories/*.stories.tsx', '../stories/**/*.stories.tsx'],
|
|
||||||
addons: [getAbsolutePath('@storybook/addon-links'), getAbsolutePath('@storybook/addon-essentials')],
|
|
||||||
framework: {
|
|
||||||
name: getAbsolutePath('@storybook/react-vite'),
|
|
||||||
options: {},
|
|
||||||
},
|
|
||||||
|
|
||||||
core: {},
|
|
||||||
|
|
||||||
async viteFinal(config, { configType }) {
|
|
||||||
// customize the Vite config here
|
|
||||||
return {
|
|
||||||
...config,
|
|
||||||
define: { 'process.env': {} },
|
|
||||||
resolve: {
|
|
||||||
alias: [
|
|
||||||
{
|
|
||||||
find: 'ui',
|
|
||||||
replacement: resolve(__dirname, '../../../packages/ui/'),
|
|
||||||
},
|
|
||||||
],
|
|
||||||
},
|
|
||||||
};
|
|
||||||
},
|
|
||||||
|
|
||||||
docs: {
|
|
||||||
autodocs: true,
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
export default config;
|
|
||||||
+10
-15
@@ -1,33 +1,28 @@
|
|||||||
{
|
{
|
||||||
"name": "docs-dev",
|
"name": "@repo/docs-dev",
|
||||||
"version": "0.0.0",
|
"version": "0.0.0",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"private": true,
|
"private": true,
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"dev": "storybook dev -p 6006",
|
"dev": "vitepress dev src --port 6060",
|
||||||
"build": "storybook build --docs",
|
"build": "vitepress build src",
|
||||||
"preview-storybook": "serve storybook-static",
|
"serve": "vitepress serve src --port 6060",
|
||||||
"clean": "rm -rf .turbo node_modules",
|
"clean": "rm -rf .turbo node_modules src/.vitepress/dist src/.vitepress/cache"
|
||||||
"lint": "eslint ./stories/*.stories.tsx --max-warnings 0"
|
|
||||||
},
|
},
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@repo/ui": "workspace:*",
|
"@repo/ui": "workspace:*",
|
||||||
|
"dayjs": "^1.11.19",
|
||||||
"react": "^19.2.3",
|
"react": "^19.2.3",
|
||||||
"react-dom": "^19.2.3"
|
"react-dom": "^19.2.3"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@repo/eslint-config": "workspace:*",
|
"@repo/eslint-config": "workspace:*",
|
||||||
"@repo/typescript-config": "workspace:*",
|
"@repo/typescript-config": "workspace:*",
|
||||||
"@storybook/addon-actions": "^8.2.6",
|
|
||||||
"@storybook/addon-essentials": "^8.2.6",
|
|
||||||
"@storybook/addon-links": "^8.2.6",
|
|
||||||
"@storybook/react": "^8.2.6",
|
|
||||||
"@storybook/react-vite": "^8.2.6",
|
|
||||||
"@vitejs/plugin-react": "^5.1.2",
|
|
||||||
"eslint": "^8.57.0",
|
"eslint": "^8.57.0",
|
||||||
"serve": "^14.2.1",
|
"mermaid": "^11.15.0",
|
||||||
"storybook": "^8.2.6",
|
|
||||||
"typescript": "5.5.4",
|
"typescript": "5.5.4",
|
||||||
"vite": "^5.1.4"
|
"vitepress": "^1.6.4",
|
||||||
|
"vitepress-plugin-mermaid": "^2.0.17",
|
||||||
|
"vue": "^3.5.38"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -0,0 +1,84 @@
|
|||||||
|
import { defineConfig } from 'vitepress'
|
||||||
|
import { withMermaid } from 'vitepress-plugin-mermaid'
|
||||||
|
|
||||||
|
const config = withMermaid(
|
||||||
|
defineConfig({
|
||||||
|
title: "Frontend Monorepo Docs",
|
||||||
|
description: "Centralized documentation for the Enterprise Frontend Monorepo",
|
||||||
|
|
||||||
|
themeConfig: {
|
||||||
|
nav: [
|
||||||
|
{ text: 'Docs', link: '/overview' },
|
||||||
|
],
|
||||||
|
|
||||||
|
sidebar: [
|
||||||
|
{
|
||||||
|
text: 'Introduction',
|
||||||
|
items: [
|
||||||
|
{ text: 'Overview', link: '/overview' },
|
||||||
|
{ text: 'Local Setup', link: '/setup' },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Core Architecture & State',
|
||||||
|
collapsed: false,
|
||||||
|
items: [
|
||||||
|
{ text: 'Core API Engine', link: '/packages/core-api/' },
|
||||||
|
{ text: 'Core Events', link: '/packages/core-events/' },
|
||||||
|
{ text: 'Core Storage', link: '/packages/core-storage/' },
|
||||||
|
{ text: 'Core Internationalization', link: '/packages/core-i18n/' },
|
||||||
|
{ text: 'IPC Architecture', link: '/apps/desktop/IPC_ARCHITECTURE' },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'UI System & Layouts',
|
||||||
|
collapsed: false,
|
||||||
|
items: [
|
||||||
|
{ text: 'UI Components Overview', link: '/packages/ui/' },
|
||||||
|
{ text: 'Core App Shell', link: '/packages/ui/CORE-APP-SHELL' },
|
||||||
|
{ text: 'Form Components', link: '/packages/ui/FORM-COMPONENTS' },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Applications & Configuration',
|
||||||
|
collapsed: false,
|
||||||
|
items: [
|
||||||
|
{ text: 'Desktop Application', link: '/apps/desktop/' },
|
||||||
|
{ text: 'Desktop Configuration', link: '/apps/desktop/CONFIGURATION' },
|
||||||
|
{ text: 'Desktop Auto Updater', link: '/apps/desktop/AUTO_UPDATER' },
|
||||||
|
],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
|
||||||
|
outline: { level: [2, 3] },
|
||||||
|
socialLinks: [],
|
||||||
|
},
|
||||||
|
|
||||||
|
// Mermaid configuration
|
||||||
|
mermaid: {
|
||||||
|
theme: 'default',
|
||||||
|
},
|
||||||
|
|
||||||
|
// Fix cascading CJS/ESM SyntaxErrors caused by Vite dynamically discovering mermaid
|
||||||
|
vite: {
|
||||||
|
optimizeDeps: {
|
||||||
|
include: [
|
||||||
|
'mermaid'
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
})
|
||||||
|
);
|
||||||
|
|
||||||
|
// Pnpm strict workspace workaround:
|
||||||
|
// vitepress-plugin-mermaid aggressively injects sub-dependencies into optimizeDeps.include.
|
||||||
|
// Because pnpm uses strict symlinks, Vite fails to resolve these sub-dependencies from the project root,
|
||||||
|
// causing pre-bundling to fail and cascading CJS/ESM SyntaxErrors in the browser.
|
||||||
|
// We strip them out so esbuild can naturally inline them into the 'mermaid' chunk instead.
|
||||||
|
if (config.vite?.optimizeDeps?.include) {
|
||||||
|
config.vite.optimizeDeps.include = config.vite.optimizeDeps.include.filter(
|
||||||
|
(dep) => !['@braintree/sanitize-url', 'debug', 'cytoscape-cose-bilkent', 'cytoscape'].includes(dep)
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
export default config;
|
||||||
@@ -1,4 +1,3 @@
|
|||||||
[← Back to Root](../../../README.md)
|
|
||||||
|
|
||||||
# Desktop Auto-Update System
|
# Desktop Auto-Update System
|
||||||
|
|
||||||
@@ -110,7 +109,8 @@ pnpm run prebuild
|
|||||||
GH_TOKEN=your_token electron-builder --publish always --config electron-builder.yml
|
GH_TOKEN=your_token electron-builder --publish always --config electron-builder.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
> [!CAUTION] > **Treat `GH_TOKEN` as a critical secret.** It grants write access to your repository's release assets. Never commit it to version control, never log it in CI output, and always inject it via encrypted secrets or a vault.
|
> [!CAUTION]
|
||||||
|
> **Treat `GH_TOKEN` as a critical secret.** It grants write access to your repository's release assets. Never commit it to version control, never log it in CI output, and always inject it via encrypted secrets or a vault.
|
||||||
|
|
||||||
### Automated Release (GitHub Actions)
|
### Automated Release (GitHub Actions)
|
||||||
|
|
||||||
@@ -172,7 +172,7 @@ jobs:
|
|||||||
|
|
||||||
1. Navigate to **Settings → Secrets and variables → Actions** in your GitHub repository.
|
1. Navigate to **Settings → Secrets and variables → Actions** in your GitHub repository.
|
||||||
2. Add each variable as a **Repository secret**.
|
2. Add each variable as a **Repository secret**.
|
||||||
3. Reference them in workflow files as `${{ secrets.VARIABLE_NAME }}`.
|
3. Reference them in workflow files as <code v-pre>${{ secrets.VARIABLE_NAME }}</code>.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -228,7 +228,8 @@ publish:
|
|||||||
|
|
||||||
Your server must host the same directory structure as the S3 layout above.
|
Your server must host the same directory structure as the S3 layout above.
|
||||||
|
|
||||||
> [!IMPORTANT] > **MIME Type Configuration**: Ensure your file server correctly serves `.yml` files with `text/yaml` and installer binaries with `application/octet-stream`. Incorrect MIME types will cause download corruption or silent update failures.
|
> [!IMPORTANT]
|
||||||
|
> **MIME Type Configuration**: Ensure your file server correctly serves `.yml` files with `text/yaml` and installer binaries with `application/octet-stream`. Incorrect MIME types will cause download corruption or silent update failures.
|
||||||
|
|
||||||
**Nginx reference:**
|
**Nginx reference:**
|
||||||
|
|
||||||
@@ -255,7 +256,8 @@ server {
|
|||||||
|
|
||||||
## 🛡️ Code Signing: The Trust Boundary
|
## 🛡️ Code Signing: The Trust Boundary
|
||||||
|
|
||||||
> [!WARNING] > **Code signing is not merely a requirement — it is the Trust Boundary established by the operating system.** macOS Gatekeeper will explicitly terminate unsigned applications or refuse background updates to maintain system integrity. Windows SmartScreen will display alarming warnings to users. Without valid signatures, `electron-updater` will **reject update payloads entirely**.
|
> [!WARNING]
|
||||||
|
> **Code signing is not merely a requirement — it is the Trust Boundary established by the operating system.** macOS Gatekeeper will explicitly terminate unsigned applications or refuse background updates to maintain system integrity. Windows SmartScreen will display alarming warnings to users. Without valid signatures, `electron-updater` will **reject update payloads entirely**.
|
||||||
|
|
||||||
### macOS
|
### macOS
|
||||||
|
|
||||||
@@ -1,4 +1,3 @@
|
|||||||
[← Back to Root](../../../README.md)
|
|
||||||
|
|
||||||
# Desktop Configuration Guide
|
# Desktop Configuration Guide
|
||||||
|
|
||||||
+16
-4
@@ -1,10 +1,21 @@
|
|||||||
[← Back to Root](../../../README.md)
|
---
|
||||||
|
outline: [2, 3]
|
||||||
|
---
|
||||||
|
|
||||||
# IPC Architecture & Security Model
|
# IPC Architecture & Security Model
|
||||||
|
|
||||||
The Secure Communication Blueprint.
|
> **Scope**: Electron Main ↔ Renderer process communication
|
||||||
|
> **Enforcement Level**: Mandatory — deviations constitute security violations
|
||||||
|
|
||||||
> This document defines the **Hardened Security Perimeter** and communication topology governing the Desktop Wrapper. Every native capability exposed to the renderer is mediated through a **Non-Bypassable IPC Bridge**, ensuring that the Node.js Main Process remains cryptographically and logically isolated from untrusted web content. Adherence to this document is **mandatory** — deviations constitute security violations subject to immediate remediation.
|
This document defines the **hardened security perimeter** and communication topology governing the Desktop Wrapper. Every native capability exposed to the Renderer is mediated through a **non-bypassable IPC bridge**, enforcing strict privilege separation between the Node.js Main Process and untrusted web content.
|
||||||
|
|
||||||
|
The architecture operates on three invariants:
|
||||||
|
|
||||||
|
| Invariant | Guarantee |
|
||||||
|
|---|---|
|
||||||
|
| **Context Encapsulation** | The Preload Script executes in a hermetically sealed V8 context, isolated from both Main Process globals and the Renderer DOM. |
|
||||||
|
| **Interface Narrowing** | Only explicitly declared, type-safe API surfaces are exposed via `contextBridge`. No wildcard access patterns exist. |
|
||||||
|
| **Deterministic Lifecycle** | All IPC subscriptions are paired with unsubscribe functions, tying native event listeners to React's component lifecycle to prevent memory leaks. |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -96,7 +107,8 @@ These settings are declared in `BrowserWindow.webPreferences` and are **non-nego
|
|||||||
|
|
||||||
Every native feature in this architecture **must** follow the Three-Step Bridge — a Standard Operating Procedure (SOP) that ensures traceability, type-safety, and auditability across the entire IPC surface.
|
Every native feature in this architecture **must** follow the Three-Step Bridge — a Standard Operating Procedure (SOP) that ensures traceability, type-safety, and auditability across the entire IPC surface.
|
||||||
|
|
||||||
> [!IMPORTANT] > **Deterministic Synchronization**: Maintaining parity between the Main Process handler, the Preload Gateway exposure, and the TypeScript interface declaration is **mandatory**. A mismatch between any two of the three layers will result in either a **Type-Safety Gap** (silent failures in development) or a **Runtime Regression** (crashes in production).
|
> [!IMPORTANT]
|
||||||
|
> **Deterministic Synchronization**: Maintaining parity between the Main Process handler, the Preload Gateway exposure, and the TypeScript interface declaration is **mandatory**. A mismatch between any two of the three layers will result in either a **Type-Safety Gap** (silent failures in development) or a **Runtime Regression** (crashes in production).
|
||||||
|
|
||||||
### Step 1: Register the Handler — Main Process
|
### Step 1: Register the Handler — Main Process
|
||||||
|
|
||||||
@@ -102,7 +102,7 @@ All artifacts are emitted to the `release/` directory.
|
|||||||
> APPLE_APP_SPECIFIC_PASSWORD=<app-specific password>
|
> APPLE_APP_SPECIFIC_PASSWORD=<app-specific password>
|
||||||
> APPLE_TEAM_ID=<team id>
|
> APPLE_TEAM_ID=<team id>
|
||||||
> ```
|
> ```
|
||||||
> Without valid code signing, macOS Gatekeeper will quarantine the application and `electron-updater` will reject update payloads. See [docs/AUTO_UPDATER.md](docs/AUTO_UPDATER.md) for the complete requirements.
|
> Without valid code signing, macOS Gatekeeper will quarantine the application and `electron-updater` will reject update payloads. See [AUTO_UPDATER.md](./AUTO_UPDATER.md) for the complete requirements.
|
||||||
|
|
||||||
> [!NOTE]
|
> [!NOTE]
|
||||||
> **Cross-Compilation Advisory**: It is strongly recommended to build for each platform on its native OS. Cross-compilation (e.g., producing `.dmg` on Linux) may fail due to platform-specific toolchain dependencies. For CI, leverage a matrix strategy:
|
> **Cross-Compilation Advisory**: It is strongly recommended to build for each platform on its native OS. Cross-compilation (e.g., producing `.dmg` on Linux) may fail due to platform-specific toolchain dependencies. For CI, leverage a matrix strategy:
|
||||||
@@ -124,7 +124,7 @@ DESKTOP_TARGET_APP=web
|
|||||||
DESKTOP_DEV_SERVER_URL=http://localhost:5173
|
DESKTOP_DEV_SERVER_URL=http://localhost:5173
|
||||||
```
|
```
|
||||||
|
|
||||||
See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for comprehensive guidance on target app switching, protocol internals, and the HashRouter fallback procedure.
|
See [CONFIGURATION.md](./CONFIGURATION.md) for comprehensive guidance on target app switching, protocol internals, and the HashRouter fallback procedure.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -140,7 +140,7 @@ Enables granular control over system peripherals — such as printers — throug
|
|||||||
|
|
||||||
### 🔄 Auto-Update Engine
|
### 🔄 Auto-Update Engine
|
||||||
|
|
||||||
A fully managed update lifecycle powered by `electron-updater`. Background download progress is forwarded in real-time to the React UI via IPC event subscriptions, enabling rich notification experiences. See [docs/AUTO_UPDATER.md](docs/AUTO_UPDATER.md).
|
A fully managed update lifecycle powered by `electron-updater`. Background download progress is forwarded in real-time to the React UI via IPC event subscriptions, enabling rich notification experiences. See [AUTO_UPDATER.md](./AUTO_UPDATER.md).
|
||||||
|
|
||||||
### 🛡️ CORS Bypass Proxy
|
### 🛡️ CORS Bypass Proxy
|
||||||
|
|
||||||
@@ -173,7 +173,7 @@ The Desktop Wrapper enforces a **hardened security perimeter**, strictly isolati
|
|||||||
- **Origin Sanitization** — `session.defaultSession.webRequest` intercepts all outgoing requests, stripping `app://` / `file://` Origin headers to prevent backend CORS rejections.
|
- **Origin Sanitization** — `session.defaultSession.webRequest` intercepts all outgoing requests, stripping `app://` / `file://` Origin headers to prevent backend CORS rejections.
|
||||||
- **Navigation Guard** — The `will-navigate` event intercepts and blocks all navigation attempts to URLs outside the `app://` protocol and the authorized dev server origin.
|
- **Navigation Guard** — The `will-navigate` event intercepts and blocks all navigation attempts to URLs outside the `app://` protocol and the authorized dev server origin.
|
||||||
|
|
||||||
See [docs/IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) for the full security model, the Three-Step Bridge pattern, and guidance on safely extending the app with new native features.
|
See [IPC_ARCHITECTURE.md](./IPC_ARCHITECTURE.md) for the full security model, the Three-Step Bridge pattern, and guidance on safely extending the app with new native features.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -181,6 +181,6 @@ See [docs/IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) for the full security m
|
|||||||
|
|
||||||
| Document | Scope |
|
| Document | Scope |
|
||||||
|---|---|
|
|---|---|
|
||||||
| [CONFIGURATION.md](docs/CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback procedure |
|
| [CONFIGURATION.md](./CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback procedure |
|
||||||
| [AUTO_UPDATER.md](docs/AUTO_UPDATER.md) | Release lifecycle, CI/CD variables, provider switching, code signing |
|
| [AUTO_UPDATER.md](./AUTO_UPDATER.md) | Release lifecycle, CI/CD variables, provider switching, code signing |
|
||||||
| [IPC_ARCHITECTURE.md](docs/IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, existing IPC channels, extensibility guide |
|
| [IPC_ARCHITECTURE.md](./IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, existing IPC channels, extensibility guide |
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
---
|
||||||
|
layout: home
|
||||||
|
hero:
|
||||||
|
name: "Frontend Monorepo Template Docs"
|
||||||
|
text: "Centralized Documentation Engine"
|
||||||
|
tagline: "Enterprise-ready Web & Desktop architecture documentation."
|
||||||
|
actions:
|
||||||
|
- theme: brand
|
||||||
|
text: Get Started
|
||||||
|
link: /packages/core-api/
|
||||||
|
- theme: alt
|
||||||
|
text: UI Components
|
||||||
|
link: /packages/ui/
|
||||||
|
features:
|
||||||
|
- title: Centralized Source of Truth
|
||||||
|
details: All documentation for apps and packages is unified here.
|
||||||
|
- title: Markdown Powered
|
||||||
|
details: Simple to maintain and read.
|
||||||
|
- title: Built with VitePress
|
||||||
|
details: Fast, responsive, and reliable documentation engine.
|
||||||
|
---
|
||||||
@@ -0,0 +1,95 @@
|
|||||||
|
# Monorepo Architecture Overview
|
||||||
|
|
||||||
|
## 📂 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, 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
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
### 9. `packages/utils`
|
||||||
|
Shared business logic and reusable utility modules that can be consumed across multiple applications. Fully tested using Vitest.
|
||||||
|
|
||||||
|
### 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 docs
|
||||||
|
* **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):
|
||||||
|
```bash
|
||||||
|
rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist out **/*/out web-dist **/*/web-dist release **/*/release
|
||||||
|
```
|
||||||
@@ -1,4 +1,3 @@
|
|||||||
[← Back to Root](../../README.md)
|
|
||||||
|
|
||||||
# Enterprise API Engine (`@repo/core-api`)
|
# Enterprise API Engine (`@repo/core-api`)
|
||||||
|
|
||||||
@@ -1,4 +1,3 @@
|
|||||||
[← Back to Root](../../README.md)
|
|
||||||
|
|
||||||
# Event Bus (`@repo/core-events`)
|
# Event Bus (`@repo/core-events`)
|
||||||
|
|
||||||
@@ -1,4 +1,3 @@
|
|||||||
[← Back to Root](../../README.md)
|
|
||||||
|
|
||||||
# i18n Architecture (`@repo/core-i18n`)
|
# i18n Architecture (`@repo/core-i18n`)
|
||||||
|
|
||||||
@@ -1,4 +1,3 @@
|
|||||||
[← Back to Root](../../README.md)
|
|
||||||
|
|
||||||
# Storage Engine (`@repo/core-storage`)
|
# Storage Engine (`@repo/core-storage`)
|
||||||
|
|
||||||
+6
-2
@@ -1,4 +1,8 @@
|
|||||||
# Core App Shell — Layout Engine Architecture & Usage Guide
|
---
|
||||||
|
outline: [2, 3]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Core App Shell — Layout Engine
|
||||||
|
|
||||||
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/components`
|
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/components`
|
||||||
> **Dependencies**: React 18+, Mantine v8 (`AppShell`), `@mantine/hooks`
|
> **Dependencies**: React 18+, Mantine v8 (`AppShell`), `@mantine/hooks`
|
||||||
@@ -74,7 +78,7 @@ packages/ui/src/components/core-app-shell/
|
|||||||
└── index.ts # Barrel exports
|
└── index.ts # Barrel exports
|
||||||
```
|
```
|
||||||
|
|
||||||
**Source**: [`core-app-shell/`](../src/components/core-app-shell/)
|
**Source**: `packages/ui/src/components/core-app-shell/`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
+6
-2
@@ -1,4 +1,8 @@
|
|||||||
# Form UI Library — Architecture & Usage Guide
|
---
|
||||||
|
outline: [2, 3]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Form UI Library
|
||||||
|
|
||||||
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/form`
|
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/form`
|
||||||
> **Dependencies**: React Hook Form v7, Zod v3, Mantine v8, `@repo/core-i18n`
|
> **Dependencies**: React Hook Form v7, Zod v3, Mantine v8, `@repo/core-i18n`
|
||||||
@@ -56,7 +60,7 @@ withRHF<MantineComponentProps>(displayName, MantineComponent, options?)
|
|||||||
└── Preserves full Mantine TypeScript generics
|
└── Preserves full Mantine TypeScript generics
|
||||||
```
|
```
|
||||||
|
|
||||||
**Source**: [`withRHF.tsx`](../src/components/Form/withRHF.tsx)
|
**Source**: `packages/ui/src/components/Form/withRHF.tsx`
|
||||||
|
|
||||||
The factory accepts three arguments:
|
The factory accepts three arguments:
|
||||||
|
|
||||||
@@ -22,7 +22,7 @@ The centralized UI component library for the monorepo. Provides consistent desig
|
|||||||
|
|
||||||
## 📋 Form UI Library
|
## 📋 Form UI Library
|
||||||
|
|
||||||
> **Full Documentation**: [docs/FORM-COMPONENTS.md](docs/FORM-COMPONENTS.md)
|
> **Full Documentation**: [FORM-COMPONENTS.md](./FORM-COMPONENTS.md)
|
||||||
|
|
||||||
The Form UI Library wraps **all 22 applicable Mantine form components** with React Hook Form via a single `withRHF()` HOC factory. Key features:
|
The Form UI Library wraps **all 22 applicable Mantine form components** with React Hook Form via a single `withRHF()` HOC factory. Key features:
|
||||||
|
|
||||||
@@ -0,0 +1,75 @@
|
|||||||
|
# Local Development Setup
|
||||||
|
|
||||||
|
## 🚀 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 **VitePress** for documentation development (strictly at `http://localhost:6060`) |
|
||||||
|
| `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 the Desktop documentation 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.
|
||||||
@@ -1,46 +0,0 @@
|
|||||||
import type { Meta, StoryObj } from '@storybook/react';
|
|
||||||
import { Button } from '@repo/ui';
|
|
||||||
|
|
||||||
const meta: Meta<typeof Button> = {
|
|
||||||
component: Button,
|
|
||||||
argTypes: {
|
|
||||||
type: {
|
|
||||||
control: { type: 'radio' },
|
|
||||||
options: ['button', 'submit', 'reset'],
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
|
|
||||||
export default meta;
|
|
||||||
|
|
||||||
type Story = StoryObj<typeof Button>;
|
|
||||||
|
|
||||||
/*
|
|
||||||
*👇 Render functions are a framework specific feature to allow you control on how the component renders.
|
|
||||||
* See https://storybook.js.org/docs/react/api/csf
|
|
||||||
* to learn how to use render functions.
|
|
||||||
*/
|
|
||||||
export const Primary: Story = {
|
|
||||||
render: (props) => (
|
|
||||||
<Button
|
|
||||||
{...props}
|
|
||||||
onClick={(): void => {
|
|
||||||
// eslint-disable-next-line no-alert -- alert for demo
|
|
||||||
alert('Hello from Turborepo!');
|
|
||||||
}}
|
|
||||||
>
|
|
||||||
Hello
|
|
||||||
</Button>
|
|
||||||
),
|
|
||||||
name: 'Button',
|
|
||||||
args: {
|
|
||||||
children: 'Hello',
|
|
||||||
type: 'submit',
|
|
||||||
style: {
|
|
||||||
color: 'blue',
|
|
||||||
border: '1px solid gray',
|
|
||||||
padding: 10,
|
|
||||||
borderRadius: 10,
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
@@ -0,0 +1,7 @@
|
|||||||
|
export default {
|
||||||
|
vite: {
|
||||||
|
optimizeDeps: {
|
||||||
|
include: ['@repo/ui', 'mermaid', 'dayjs']
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,14 @@
|
|||||||
|
import { defineConfig } from 'vitepress'
|
||||||
|
import { withMermaid } from 'vitepress-plugin-mermaid'
|
||||||
|
|
||||||
|
const baseConfig = withMermaid(
|
||||||
|
defineConfig({
|
||||||
|
title: "Test",
|
||||||
|
})
|
||||||
|
);
|
||||||
|
|
||||||
|
console.log("Before:", baseConfig.vite.optimizeDeps.include);
|
||||||
|
baseConfig.vite.optimizeDeps.include = baseConfig.vite.optimizeDeps.include.filter(
|
||||||
|
(dep) => !['@braintree/sanitize-url', 'debug', 'cytoscape-cose-bilkent', 'cytoscape'].includes(dep)
|
||||||
|
);
|
||||||
|
console.log("After:", baseConfig.vite.optimizeDeps.include);
|
||||||
@@ -1,4 +0,0 @@
|
|||||||
import { defineConfig } from 'vite';
|
|
||||||
import react from '@vitejs/plugin-react';
|
|
||||||
|
|
||||||
export default defineConfig({ plugins: [react()] });
|
|
||||||
Generated
+1517
-946
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user