Add Meridian, a simulated fleet monitoring demo

.env.example

@@ -0,0 +1,9 @@
+# Bake the in-browser simulator into the bundle and skip the server probe.
+# GitHub Pages sets this. Leave it unset locally so `npm run dev` uses the Node simulator.
+# VITE_FORCE_BROWSER=true
+
+# Optional absolute WebSocket URL. Defaults to the page host + /ws (Vite proxies /ws in dev).
+# VITE_WS_URL=ws://127.0.0.1:8787/ws
+
+# Port for the Node simulator.
+# PORT=8787

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Typecheck
+        run: npm run typecheck
+      - name: Unit tests
+        run: npm test
+      - name: Install Playwright
+        run: npx playwright install --with-deps chromium
+      - name: Smoke test
+        run: npm run test:e2e

.github/workflows/pages.yml

@@ -0,0 +1,45 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - uses: actions/configure-pages@v5
+      - run: npm ci
+      - name: Build static demo
+        run: npm run build
+        env:
+          VITE_FORCE_BROWSER: 'true'
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+coverage
+playwright-report
+test-results
+blob-report
+.DS_Store
+*.local
+.env
+.env.*
+!.env.example

.prettierignore

@@ -0,0 +1,6 @@
+dist
+node_modules
+coverage
+playwright-report
+test-results
+package-lock.json

.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "printWidth": 96,
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "all"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arpan Bom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,106 @@
-# react-ts-fleet-dashboard
-React + TypeScript real-time fleet monitoring dashboard
+# Meridian
+
+Real-time fleet operations console for ground vehicles and drones. This is a **portfolio demo** by [Arpan Bom](https://github.com/applycoding). The tracks, batteries, and alerts are simulated. Nothing here is connected to a live vehicle, a drone remote ID feed, or an operations center.
+
+[![CI](https://github.com/applycoding/react-ts-fleet-dashboard/actions/workflows/ci.yml/badge.svg)](https://github.com/applycoding/react-ts-fleet-dashboard/actions/workflows/ci.yml)
+
+The same deterministic simulator runs in two places:
+
+- a small Node server with HTTP snapshots and a WebSocket tick, for local development
+- the browser itself, when that server is not there (including the GitHub Pages build)
+
+## Screenshots
+
+![Meridian dashboard in dark mode, with the bay map, unit list, telemetry, and alerts](docs/screenshots/desktop-dark.png)
+
+![The same dashboard pinned to light mode](docs/screenshots/desktop-light.png)
+
+![Stacked layout on a phone-width viewport](docs/screenshots/mobile-dark.png)
+
+## Features
+
+- Live map (Leaflet, CARTO basemaps from OpenStreetMap data) with moving ground and drone markers and a restricted-airspace box
+- Unit list with search, kind, and status filters
+- Telemetry for the selected unit: speed, battery, altitude, and heading over the last few minutes
+- Alerts for low battery, intermittent links, and drones inside the restricted box, with acknowledge
+- Light, dark, and system color schemes, without a flash of the wrong scheme
+- Layout that stacks on narrow viewports
+- Vitest and Testing Library coverage, plus a Playwright smoke test
+- GitHub Actions CI and a GitHub Pages workflow that ships the in-browser simulator
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph browser [Browser]
+    UI[React panels]
+    Z[Zustand UI state]
+    Q[TanStack Query]
+    SIM[In-browser engine]
+    UI --> Z
+    UI --> Q
+    Q -->|server missing| SIM
+  end
+
+  subgraph node [Optional Node simulator]
+    HTTP[HTTP /api]
+    WS[WebSocket /ws]
+    ENG[Shared engine]
+    HTTP --> ENG
+    WS --> ENG
+  end
+
+  Q -->|local dev| HTTP
+  Q -->|local dev| WS
+```
+
+`src/sim` is the shared engine. Position is a function of time along a fixed route, so the server and the browser draw the same tracks. The React app keeps fleet snapshots and history in TanStack Query. Filters, the selected unit, acknowledgements, and the data-source mode live in Zustand.
+
+On startup the page asks `/api/health`. A response means “live socket”. A miss, or `VITE_FORCE_BROWSER=true` in the Pages build, means the tab runs the engine itself.
+
+## Stack
+
+React 18, TypeScript, Vite, TanStack Query, Zustand, Leaflet, Vitest, Testing Library, Playwright, ESLint, Prettier.
+
+## Run it
+
+```bash
+npm install
+npm run dev
+```
+
+- App: http://localhost:5173
+- Simulator: http://127.0.0.1:8787 (`/api/health`, `/api/snapshot`, `/api/units/:id/history`, `POST /api/alerts/:id/ack`, WebSocket `/ws`)
+
+The Vite dev server proxies `/api` and `/ws` to the simulator. Stop the simulator and reload: the badge switches to **Browser sim** and the map keeps moving.
+
+```bash
+npm run dev:server   # simulator only
+npm run dev:client   # Vite only
+npm run build
+npm run preview
+```
+
+`npm run build` writes a static `dist/` that does not need the Node process.
+
+## Tests
+
+```bash
+npm run lint
+npm test
+npm run test:e2e
+```
+
+`test:e2e` builds the static app, serves it, and checks that the in-browser fleet renders and the drone filter works. CI runs lint, the typecheck, unit tests, and that smoke test.
+
+## GitHub Pages
+
+`.github/workflows/pages.yml` builds with `VITE_FORCE_BROWSER=true` and deploys `dist/` with GitHub Pages actions. In the repository settings, set **Pages → Build and deployment → Source** to **GitHub Actions**. After the first deploy on `main` the site is at:
+
+https://applycoding.github.io/react-ts-fleet-dashboard/
+
+Map tiles are loaded from CARTO’s public basemap host. That is fine for a demo; it is not a tile service you should put in front of real traffic.
+
+## License
+
+[MIT](LICENSE) © 2026 Arpan Bom

e2e/smoke.spec.ts

@@ -0,0 +1,19 @@
+import { expect, test } from '@playwright/test';
+
+test('shows the simulated fleet and filters to drones', async ({ page }) => {
+  await page.goto('./');
+  await expect(page.getByRole('heading', { level: 1, name: 'Meridian' })).toBeVisible();
+  await expect(page.getByRole('option', { name: /M-14/ })).toBeVisible();
+  await expect(page.getByText('Browser sim')).toBeVisible();
+
+  await page
+    .getByRole('group', { name: 'Unit kind' })
+    .getByRole('button', { name: 'Drones' })
+    .click();
+  await expect(page.getByRole('option', { name: /M-14/ })).toHaveCount(0);
+  await expect(page.getByRole('option', { name: /D-12/ })).toBeVisible();
+
+  await page.getByRole('option', { name: /D-12/ }).click();
+  await expect(page.getByRole('region', { name: 'Telemetry' })).toContainText('D-12');
+  await expect(page.getByRole('img', { name: /Speed in km\/h/ })).toBeVisible();
+});

eslint.config.js

@@ -0,0 +1,35 @@
+import js from '@eslint/js';
+import prettier from 'eslint-config-prettier';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: [
+      'dist/**',
+      'node_modules/**',
+      'playwright-report/**',
+      'test-results/**',
+      'coverage/**',
+    ],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+      ],
+    },
+  },
+  prettier,
+);

index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <script>
+      try {
+        var stored = localStorage.getItem('color-scheme');
+        if (stored === 'light' || stored === 'dark') {
+          var meta = document.querySelector('meta[name="color-scheme"]');
+          if (meta) meta.setAttribute('content', stored);
+        }
+      } catch (error) {
+        /* Storage can be blocked. The page still follows the system scheme. */
+      }
+    </script>
+    <title>Meridian — Fleet operations</title>
+    <meta
+      name="description"
+      content="Portfolio demo of a real-time vehicle and drone fleet monitor. Telemetry is simulated."
+    />
+    <link rel="icon" href="./favicon.svg" type="image/svg+xml" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,560&family=IBM+Plex+Mono:wght@400;500&family=Outfit:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>