Orbit is a full-stack execution + foresight assistant: you give tasks, mood, time, and goals; it returns one auditable next action, ranked alternatives, Sentinel-style risk language, and (when configured) richer narrative via Google Gemini. The React app also includes a life calendar, long-term goal ladders, visit streaks, and optional Supabase auth so profile data can sync to PostgreSQL (hosted by Supabase).
| Area | What you get |
|---|---|
| Next action | POST /generate-next-action — weighted scoring (urgency, goal alignment, feasibility, risk reduction), top-3 Sentinel snapshots, composite confidence. |
| Schedule | POST /generate-schedule — multi-agent style pipeline including duration hints/keyword predictions and packing into a day/week view. |
| Long-term planning | POST /plan-long-term-steps — structured steps for big goals (Gemini-backed when configured). |
| Frontend | Vite + React: tasks, mood, time/hours, goals, results, ranking UI, calendar month, streak pills, Supabase email/password auth when env is set. |
| Account sync | With Supabase + profiles table: streaks, structured goals JSON, calendar JSON synced via /me/* routes. |
- Frontend: React 19, Vite,
fetch,@supabase/supabase-js, CSS modules / component styles - Backend: Node.js (ESM), Express 5,
cors,dotenv - AI:
@google/generative-ai(Gemini) for narrative polish and planning helpers - Auth & data: Supabase Auth + PostgreSQL (
profiles,daily_visits) — seebackend/supabase/schema.sql - Local-only fallbacks:
localStoragefor offline-first pieces when not signed in or for caching
- Node.js 20+ recommended
- npm
- Google AI Studio API key if you want Gemini narrative (optional — core routes still return deterministic copy when the key is missing)
- Supabase project if you want sign-in and cloud sync (optional for local-only demo)
git clone <your-repo-url> orbit-ai
cd orbit-aiInstall both apps:
cd backend && npm install && cd ..
cd frontend && npm install && cd ..Copy backend/.env.example → backend/.env and fill in:
| Variable | Purpose |
|---|---|
PORT |
HTTP port (default 5050) |
GEMINI_API_KEY |
Optional — enables Gemini narrative / planning quality |
GEMINI_MODEL |
Optional override (see .env.example) |
SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY |
Optional — required for /me/* account routes |
Run SQL in the Supabase dashboard from backend/supabase/schema.sql before relying on auth sync.
Start the API:
cd backend
npm startHealth check: http://localhost:5050/health
Copy frontend/.env.example → frontend/.env.development.local:
| Variable | Purpose |
|---|---|
VITE_API_URL |
Backend origin (default http://localhost:5050) |
VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY |
Required only if you use Supabase auth in the UI |
cd frontend
npm run devOpen the URL Vite prints (often http://localhost:5173). If the backend uses another port, set VITE_API_URL to match.
| Method | Path | Description |
|---|---|---|
GET |
/ |
Plain text — backend alive |
GET |
/health |
JSON — Gemini / Supabase flags |
POST |
/generate-next-action |
Main decision loop (tasks, mood, time, goals, optional memory/behavior) |
POST |
/generate-schedule |
Schedule + duration agent pipeline |
POST |
/plan-long-term-steps |
Long-term goal step plan |
GET/POST |
/me/* |
Profile, visit streak, state sync (when Supabase is configured) |
Request/response shapes are easiest to learn from backend/test/orbit.test.js and the frontend fetch calls.
- One task per line, or several on one line separated by commas or semicolons (unless the line contains
est:/due:— then it stays one structured task). - Optional per line:
est:90,90min,due:2026-04-22,after:task_0(ordering hint). - Time: minutes as a number, or phrases like
2 hours,1h 30m.
orbit-ai/
├── frontend/ # React + Vite
├── backend/
│ ├── server.js # Express entry
│ ├── src/ # Orbit core, agents, routes
│ ├── supabase/ # SQL schema for profiles
│ └── test/ # Node test runner
└── README.md