HarborChain Simulation Prototype

A prototype for marina operations with a hybrid architecture:

• Simulated vessel telemetry, alerts, and workflow UI with conceptual ledger terminology
• SQLite persistence and REST API for local state durability
• Live weather integration for Dana Point using OpenWeatherMap
• Authentication skeleton with a Marina Operator role
• Scenario engine unit tests to verify critical behavior

What is real

• /api/vessels persists vessel state in SQLite under data/harborchain.db
• /api/weather fetches live conditions from OpenWeatherMap for Dana Point
• /api/auth/me and /api/auth/login provide an auth skeleton for role-based UI flows
• src/hooks/useHarborSimulation.ts separates business logic from presentation
• src/lib/scenarioEngine.ts contains the scenario engine and is covered by tests

What is still simulated

• Vessel health, bilge alarms, and charter transactions are still demo data
• Chain and ledger concepts shown in the UI are conceptual simulation labels, not live on-chain integrations
• Compliance report generation remains a mock or Gemini fallback unless GEMINI_API_KEY is configured
• The UI is a prototype cockpit, not a production operator dashboard

Run Locally

Prerequisites: Node.js

1. Install dependencies: npm install
2. Copy .env.example to .env and add your keys:
   • OPENWEATHER_API_KEY
   • GEMINI_API_KEY (optional)
3. Run the app: npm run dev
4. Run tests: npm test

GitHub CI

A GitHub Actions workflow is included at .github/workflows/ci.yml. It runs on pushes and pull requests to main/master, and executes:

• npm ci
• npm run lint
• npm test
• npm run build

Notes

• The app uses local SQLite persistence via sql.js for portable state durability.
• The auth flow is intentionally lightweight so the Marina Operator role can be extended later with Clerk or Auth0.
• Transparency is important: the app now clearly separates real API-backed features from the simulation layer.