# DigitalTwin Frontend Developer Guide (fe-digitaltwin-v2)

> [!IMPORTANT]
> **Start here before creating or handing off frontend work**
>
> - 🎨 **Design-system guideline:** Open the public
>   [`/design-system`](http://localhost:3002/design-system) page to inspect the
>   project’s tokens, typography, reusable shadcn-style components, MapCN
>   examples, and AI development workbench. Also read
>   [`prompts/design-system.md`](./prompts/design-system.md).
> - 🌿 **Feature branch and developer handoff:** Open the
>   [`Feature handoff`](http://localhost:3002/design-system#feature-handoff)
>   section for the visual `main → feature branch → developer → review`
>   workflow, safe commands, and copyable handoff generator. Also read
>   [`prompts/feature-branch-handoff.md`](./prompts/feature-branch-handoff.md)
>   and [`GIT_BRANCHES.md`](./GIT_BRANCHES.md).
>
> Reuse existing components and semantic tokens, create focused feature work
> from `main`, and never hand-edit generated `client/<slug>` branches.

Welcome to the **fe-digitaltwin-v2** project. This guide provides a clear and simple overview of our framework stack, development workflows, production build processes, and key benefits.

---

## 🚀 The Framework Stack

This project is built using a modern frontend stack designed for speed, type safety, and rich user interfaces:
*   **Core Framework**: **React 18** (with TypeScript for full type safety).
*   **Build Tool & Dev Server**: **Vite 6** (provides instantaneous hot module replacement and lightning-fast builds).
*   **Styling**: **Tailwind CSS** combined with UI libraries like **HeroUI** and **Mantine** for rich, premium interfaces.
*   **State Management**: **Zustand** (global state), **Jotai** (atomic state), and **React Query** (server cache / data fetching).
*   **Routing**: **React Router Dom v7**.

---

## 🛠️ Development Flow & Process

### 1. Prerequisites
Ensure you have **Node.js** (v18+ recommended) and **npm** installed on your machine.

### 2. Install Dependencies
Run this command from the root of the project to install all required libraries:
```bash
npm install
```

### 3. Local Development Server
Start the local development server by running:
```bash
npm run dev
```
*   **Vite Advantage**: This boots up almost instantly because it leverages native ES modules instead of pre-bundling the entire codebase.
*   **Hot Module Replacement (HMR)**: Changes you make in code are instantly reflected in the browser without losing application state.
*   **Vite Proxy**: Any API requests made to `/api-proxy` are automatically forwarded to the backend service (configured at `http://192.168.1.82:8000`) to avoid CORS issues during development.

### 4. Code Conventions & Path Aliases
To avoid messy relative imports (e.g. `../../../../components`), we use configured path aliases in `vite.config.ts` and `tsconfig.json`:
*   `@/components` ➔ maps to `src/shared/components`
*   `@/lib/api-url` ➔ maps to `src/shared/api-url`
*   `@/lib/fetcher` ➔ maps to `src/shared/fetcher`
*   `@/lib/APIs/types` ➔ maps to `src/shared/types`
*   `@` ➔ maps to `src`

---

## 📦 Production Build Flow

Before deploying to production, the codebase must be compiled, type-checked, and bundled into optimized static assets.

### 1. Build for Production
Run the build script:
```bash
npm run build
```

Under the hood, this command executes:
```bash
tsc -b && vite build
```
1.  **`tsc -b`**: Runs the TypeScript compiler in build mode to verify type correctness across the entire application. If there are any type mismatches, the build will fail, preventing runtime errors.
2.  **`vite build`**: Bundles, minifies, and optimizes your JavaScript, CSS, and asset files. Vite uses **Rollup** under the hood to perform tree-shaking (removing unused code) and code-splitting (splitting assets into smaller chunks for faster page loading).

### 2. Preview the Production Build Locally
To test the output of the production build locally before actual deployment, run:
```bash
npm run preview
```
This starts a local static file server hosting the contents of the built `dist` folder.

### 3. Docker Deployment

The production image (`Dockerfile`) builds the Vite bundle, then serves it
through **nginx**, which also reverse-proxies every backend API prefix
(`/auth`, `/efficiency`, `/pfi`, `/lcca`, `/reliability`, `/risk-matrix`,
`/monitoring`, `/rbd`, `/ahm`, `/ops-dock`, `/optimumoh`, `/ircfa`, `/api`)
to the real backend server-side (see `nginx.conf`).

This matters for tunneling: all `VITE_*_APP_URL` values are baked in as
**relative paths** by default, so the browser only ever calls the app's own
origin. When you tunnel this container's port (ngrok, cloudflared, etc.),
the browser never tries to reach the backend's local IP directly — nginx
inside the container forwards those calls to the backend for you.

```bash
docker compose up -d --build
```

The app is then available at `http://localhost:8081` (configurable via
`FRONTEND_PORT`) — tunnel **this** port, not the backend's.

By default nginx forwards API calls to `http://192.168.1.82:8000` (and
`http://192.168.1.119:8000` for IRCFA, which runs on a separate host). To
point at a different backend without rebuilding the image, copy
`.env.docker.example` to `.env.docker`, adjust `BACKEND_URL` /
`BACKEND_URL_IRCFA` / `FRONTEND_PORT`, and run:

```bash
docker compose --env-file .env.docker up -d --build
```

> **SSO caveat:** if you need SSO login to work for outside users, set the
> `VITE_AUTH_URL` build arg (in `docker-compose.yml`) to the actual public
> tunnel URL and rebuild — it's baked in as the OAuth `redirect_uri` sent to
> the identity provider, and PLN's IAM must have that exact URL
> allow-listed, or the login redirect will go nowhere.

---

## 📋 Summary of Key Commands

| Command | Purpose | When to Use |
| :--- | :--- | :--- |
| `npm install` | Installs all project dependencies | When setting up the project or after dependencies change |
| `npm run dev` | Starts the local interactive Vite development server | During active coding and daily feature development |
| `npm run build` | Compiles TypeScript and builds optimized production files | Before deploying code to production |
| `npm run preview` | Serves the production-built code locally for testing | To verify that the production bundle works correctly |
| `npm run lint` | Runs ESLint to check for code quality and styling errors | Before committing code or during CI/CD checks |

---

## 💎 Why Vite & This Stack? (Key Benefits)

1.  **Instant Startup**: Unlike traditional bundlers (like Webpack) which bundle the entire app before serving, Vite only processes the code requested by the browser on demand.
2.  **Unmatched HMR Speed**: Hot Module Replacement speed remains lightning fast regardless of the size of the application.
3.  **Type Safety**: TypeScript prevents standard runtime bugs during compilation.
4.  **Optimized Assets**: CSS and JS are split, minified, and bundled to ensure the end-user downloads only what they need, resulting in high performance and fast load times.

---

## ⚡ Why Vite + React is More Efficient Than Next.js (For This Project)

> **Source**: This section is based on the official internal Frontend Refactor PRD — *"Frontend Refactor: Next.js → Vite + React, Migration PRD & Implementation Guide, Version 1.0"* (`ref/frontend_refactor_prd.pdf`).

The previous frontend was built on **Next.js (App Router)**. After analysis, it was decided to migrate to **Vite + React**. The core reason: **this application uses zero Server-Side Rendering (SSR) or Static Site Generation (SSG)** — meaning every single page was already marked `'use client'`. Next.js was adding complexity with zero benefit.

### Side-by-Side Comparison

| Concern | Next.js (Before) | Vite + React (Now) |
| :--- | :--- | :--- |
| **Rendering** | All pages were `'use client'` — SSR was unused overhead | Pure Client-Side Rendering by design, no wasted config |
| **Routing** | App Router conventions + layouts overhead | React Router v7 — explicit, simple, easy to read |
| **Auth** | NextAuth tightly coupled to Next.js internals | Custom `useAuth` hook, full control in ~80 lines |
| **Data Fetching** | SWR + manual token threading | React Query with centralized, clean config |
| **Bundle Config** | Next.js opinionated build pipeline | Vite — fast, transparent, fully flexible |
| **Mental Model** | Server/client boundary confusion | Pure React — no framework magic, simpler onboarding |

### What Was Eliminated

*   ❌ All `'use client'` directive boilerplate — **not needed in Vite**.
*   ❌ **NextAuth / Auth.js** — replaced by a lightweight custom `AuthProvider + useAuth` hook.
*   ❌ **SWR** — replaced by **React Query** (TanStack Query v5) with a single centralized config.
*   ❌ **Next.js file-based routing** — replaced by an explicit, readable `router/index.tsx` using React Router v7.
*   ❌ **`NEXT_PUBLIC_` env variable prefix** — replaced by the simpler `VITE_` prefix via `import.meta.env`.

### What Was Gained

*   ✅ **Faster HMR**: Vite's dev server starts almost instantly and stays fast at any project scale.
*   ✅ **Simpler Mental Model**: No server/client boundary confusion. Everything is pure React.
*   ✅ **Full Auth Control**: The custom `AuthProvider` replicates everything NextAuth did in ~80 lines, with no external dependency lock-in.
*   ✅ **Better DX (Developer Experience)**: Easier onboarding for new developers — no Next.js-specific conventions to learn.
*   ✅ **Transparent Build Pipeline**: `vite build` is predictable and fully configurable, unlike Next.js's opinionated pipeline.
*   ✅ **Feature-Based Architecture**: A clean `features/` folder structure (one folder per domain) replaces the mixed `app/` directory convention.

### Migration Goals (from PRD)

The refactor was driven by these official goals:
1. Eliminate Next.js overhead (App Router, server/client split, SSR config).
2. Adopt a clean, feature-based folder structure from scratch.
3. Replace Auth.js (NextAuth) with a lightweight custom JWT auth layer.
4. Replace SWR with React Query (TanStack Query) for data fetching.
5. Maintain full feature parity — no regressions.
6. **Improve DX**: faster HMR, simpler mental model, easier team onboarding.