OceanOS

A full-stack, real-time ocean health monitoring and conservation management system powered by AI.

🌐 View the Detailed Platform Website

OceanOS is an integrated marine conservation platform that simulates, monitors, and manages ocean cleanup operations in real time. It combines a Node.js backend, an interactive admin dashboard, a fisherman incentive app, and multiple standalone 3D simulations — all communicating via WebSockets and a REST API.

Built with a local-first approach using sql.js for zero-dependency database storage, OceanOS is designed to run entirely on your machine with no cloud infrastructure required (except for the Gemini AI feature).

OceanOS/
│
├── backend/                 # Express.js REST API + WebSocket server
│   ├── server.js            # Main server (API routes, DB, WebSocket, Gemini)
│   ├── package.json
│   ├── .env                 # Your API key goes here (not committed)
│   └── .env.example         # Template for .env
│
├── dashboard/               # Admin monitoring dashboard (HTML/CSS/JS)
│   ├── index.html
│   ├── app.js               # Dashboard logic, charts, WebSocket client
│   └── style.css
│
├── fisherman-app/           # Fisherman incentive & reporting app (HTML/CSS/JS)
│   ├── index.html
│   ├── app.js
│   └── style.css
│
├── simulation/              # MAIN Unified 3D world simulation (Three.js)
│   ├── index.html           # Connected to backend, dashboard & fisherman app
│   └── world.js             # Full world engine
│
├── ocean-drone-sim/         # Standalone: Drone patrol simulation
│   ├── index.html
│   ├── main.js
│   └── style.css
│
├── ocean-pollution-sim/     # Standalone: Ocean pollution simulation
│   ├── index.html
│   ├── main.js
│   └── style.css
│
├── river simulator/         # Standalone: River plastic collection sim (Vite/TS)
│   ├── index.html
│   ├── main.js
│   ├── src/
│   └── package.json
│
├── ocean clean/             # Standalone: Ocean boom cleanup sim (Vite/TS)
│   ├── index.html
│   ├── main.js
│   ├── src/
│   └── package.json
│
├── flowchart.html           # Interactive system architecture flowchart
├── start-all.ps1            # One-click startup script (Windows PowerShell)
├── LICENSE
├── CONTRIBUTING.md
└── README.md

• Node.js v18 or higher
• A modern browser (Chrome, Firefox, Edge)
• A Gemini API key from Google AI Studio (free)

git clone (https://github.com/ishaaqdev/OceanOS.git)
cd 

cd backend
npm install

Copy the environment template and add your Gemini API key:

# Windows
copy .env.example .env

# macOS / Linux
cp .env.example .env

Open .env and replace the placeholder:

GEMINI_API_KEY=your_gemini_api_key_here

From the project root, run the PowerShell startup script:

.\start-all.ps1

This will launch 4 services simultaneously:

The script will automatically open the dashboard in your browser.

Open 4 separate terminal windows and run each of the following:

Terminal 1 — Backend:

cd backend
node server.js

Terminal 2 — Dashboard:

cd dashboard
npx serve -l 3002

Terminal 3 — Fisherman App:

cd fisherman-app
npx serve -l 3003

Terminal 4 — Main Simulation:

cd simulation
npx serve -l 3004

The standalone simulations are independent — they do not require the backend or other services to run. Open them directly in your browser or use a simple file server.

Just double-click the index.html file inside each folder.

# Drone Patrol Simulation
cd ocean-drone-sim
npx serve .

# Ocean Pollution Simulation
cd ocean-pollution-sim
npx serve .

# River Collector Simulation (Node.js required)
cd "river simulator"
npm install
npm run dev

# Ocean Cleanup Boom Simulation (Node.js required)
cd "ocean clean"
npm install
npm run dev

The backend exposes a REST API at http://localhost:3001.

WebSocket: Connect to ws://localhost:3001 for live event streaming.

Open flowchart.html in your browser to see an interactive visual diagram of the full system architecture — data flows, API connections, WebSocket events, and module relationships.

• API keys are stored in backend/.env and are never committed to the repository.
• .env.example is provided as a safe template.
• The database file (oceanos.db) is also excluded from version control.

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

This project is licensed under the MIT License — see the LICENSE file for details.