Riptide (formerly OceanGuard) is an AI-powered platform for ocean health, cleanup operations, and community impact. It combines real-time monitoring, a 3D drone simulation, voice-enabled outreach, and an in-app AI assistant (Riptide) to support sustainability and social good.

• Features
• Tech Stack
• Project Structure
• API Integrations
• Environment & Setup
• Running the App
• Pushing to GitHub

• Dashboard – Overview of scans, alerts, cleanup operations, and live stats.
• Global tracking – City-level ocean/marine monitoring (kelp, trash, water quality) with tracks and predictions.
• Cleanup – Cleanup operations, donations, and job applications; optional voice briefing (Twilio + ElevenLabs) per operation.
• Live Ops – Incidents, claims, resolutions, leaderboard, missions, and crisis/demo modes.
• Drone – Drone demo with scan reporting and a 3D Mapbox simulation (California coast, patrol path, pollution hotspots, follow-drone camera).
• Impact & analytics – Impact metrics, reports, analytics, and visualizations (e.g. Recharts, Leaflet).
• Game & scoreboard – School/team scoreboard, actions, and AI-generated briefings.
• AI chatbot (Riptide) – In-app assistant with access to live data; powered by Groq (primary) or OpenAI.

• Map styles – Toggle between Satellite and Streets (outdoors).
• 3D terrain – Mapbox DEM for elevation; works in both styles.
• Patrol path – Animated drone along a California coast route; Follow drone mode for a chase camera.
• Pollution hotspots – Markers for plastic, oil, algae, ghost gear, sewage with labels and short descriptions on click.

• Twilio – Outbound calls; webhooks for answer, speech processing, and status (requires a public URL, e.g. ngrok).
• ElevenLabs – Text-to-speech for voice agent and briefings.
• Voice bridge – Real-time conversation (Twilio ↔ ElevenLabs/OpenAI) with transcripts and call logs.

├── client/                 # Vite React app
│   ├── src/
│   │   ├── components/     # Shared UI (RiptideIsland, FloatingNav, chatbot, etc.)
│   │   ├── pages/          # Route-level pages (dashboard, cleanup, drone-simulation, etc.)
│   │   ├── lib/            # Utilities, page styles
│   │   └── App.tsx
│   └── index.html
├── server/                 # Express API and server logic
│   ├── index.ts            # Entry, mounts routes and Vite dev middleware
│   ├── routes.ts           # Main REST API (scans, alerts, cleanup, Twilio, TTS, etc.)
│   ├── chatbot.ts         # /api/chat, /api/live-stats (Riptide AI)
│   ├── twilio-bridge.ts    # Twilio webhooks, voice ↔ AI
│   ├── calling.ts         # Outbound call initiation (Twilio)
│   ├── elevenlabs.ts      # TTS (ElevenLabs)
│   ├── drone.ts           # /api/drone/report, voice report
│   ├── liveops.ts         # Live Ops API
│   ├── game.ts            # Game/scoreboard API
│   ├── voice.ts           # Voice briefing API
│   ├── forecast.ts        # Predictions / forecasting
│   ├── trust.ts           # Trust score API
│   ├── snowflake.ts       # Snowflake Cortex (optional)
│   ├── mongodb.ts         # Optional MongoDB sync
│   ├── storage.ts         # Drizzle-backed storage helpers
│   ├── db.ts              # DB client
│   └── vite.ts            # Vite dev middleware
├── shared/
│   └── schema.ts          # Drizzle schema, Zod insert schemas
├── script/
│   └── build.ts           # Production build (Vite + esbuild)
├── .env.example            # Env template (never commit .env)
└── package.json

• Endpoint: GET /api/mapbox-token → { token } (from MAPBOX_ACCESS_TOKEN).
• Usage: client/src/pages/drone-simulation.tsx uses react-map-gl + mapbox-gl; terrain is applied in onLoad and on style change.

• Endpoints:
  • POST /api/twilio/answer – Incoming call handler.
  • POST /api/twilio/process-speech – User speech → AI → TTS.
  • POST /api/twilio/status – Call status.
  • POST /api/tts – TTS request (returns audio id).
  • GET /api/tts/audio/:id – Stream TTS audio.
• Cleanup: POST /api/cleanup/:id/call starts an outbound call for a cleanup operation; Twilio hits the above webhooks.

• Scans & alerts: GET/POST /api/scans, GET/POST /api/alerts, PATCH /api/alerts/:id/resolve.
• Cleanup & donations: GET/POST/PATCH /api/cleanup, GET/POST/PATCH /api/donations, POST /api/cleanup/:id/call.
• Chatbot: POST /api/chat, GET /api/live-stats.
• Mapbox: GET /api/mapbox-token.
• Twilio / TTS: POST /api/twilio/answer, POST /api/twilio/process-speech, POST /api/twilio/status, POST /api/tts, GET /api/tts/audio/:id.
• Call logs: GET /api/call-logs, GET /api/call-logs/:id/status, GET /api/call-logs/:id/transcript-stream.
• Integrations status: GET /api/integrations/status (Twilio, ElevenLabs).
• Cities & tracking: GET /api/cities, GET /api/tracks, GET /api/predictions/:cityId, GET /api/weather/:cityId.
• Live Ops: GET /api/liveops/incidents, POST /api/liveops/claim/:id, POST /api/liveops/resolve/:id, etc.
• Game / scoreboard: GET/POST /api/game/leaderboard, POST /api/game/briefing, GET/POST /api/scoreboard/*.
• Cleanup jobs: GET/POST /api/cleanup-jobs, POST /api/cleanup-jobs/generate/:cleanupId, GET/POST /api/job-applications.
• Impact: GET /api/impact/metrics.
• Drone: POST /api/drone/report, POST /api/drone/voice-report.

1. Clone and install

   cd /path/to/Riptide-H4H-2026
   npm install

2. Database

   • Create a PostgreSQL database (e.g. oceanguard).
   • Copy .env.example to .env and set DATABASE_URL.
   • Run migrations: npm run db:push.

3. Environment variables

   • Required: DATABASE_URL, and at least one of GROQ_API_KEY or AI_INTEGRATIONS_OPENAI_API_KEY.
   • 3D simulation: MAPBOX_ACCESS_TOKEN (from Mapbox).
   • Voice: TWILIO_*, ELEVENLABS_API_KEY, and for local dev PUBLIC_DOMAIN (e.g. ngrok host).
   • See .env.example for all options; never commit .env.

• Development: npm run dev (Express + Vite dev server; default port 5000).
• Production build: npm run build (client → dist/public, server → dist/index.cjs).
• Production run: npm start (serves built client and API).

1. Create the repository on GitHub

   • Go to GitHub.
   • Repository name: Riptide-H4H-2026.
   • Do not initialize with a README (this project already has one).

2. Initialize Git (if needed) and add remote

   cd /path/to/oceanguard-project   # or your project folder
   git status                       # confirm it’s a repo and see what’s untracked
   git remote add origin https://github.com/YOUR_USERNAME/Riptide-H4H-2026.git
   # Or with SSH:
   # git remote add origin git@github.com:YOUR_USERNAME/Riptide-H4H-2026.git

3. Commit and push

   git add .
   git commit -m "Initial commit: Riptide H4H 2026 - AI for social good"
   git branch -M main
   git push -u origin main

Replace YOUR_USERNAME with your GitHub username. If the repo already had a different remote, use git remote set-url origin ... instead of git remote add origin ....

MIT.