Helios

Collaborative timezone-aware scheduling platform with 3D globe visualization.

Helios makes global time coordination intuitive by visualizing availability across time zones in a shared spatial interface. It eliminates manual time conversion by combining intelligent scheduling, real-time collaboration, and a globe-based view of time itself.

Quick Start

Prerequisites

• Docker (for PostgreSQL)
• Node.js 18+
• Python 3.11+

1. Start the database

docker compose up -d

2. Setup the backend

cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file
cp .env.example .env

# Run migrations
alembic upgrade head

# Start the server
uvicorn app.main:app --reload

Backend runs at http://localhost:8000

3. Setup the frontend

cd frontend

# Install dependencies
npm install

# Copy environment file
cp .env.example .env.local

# Start dev server
npm run dev

Frontend runs at http://localhost:3000

Features

• Anonymous-first: Join sessions without an account
• Real-time collaboration: See availability updates instantly
• Timezone-aware: Automatic timezone detection and conversion
• Optimal scheduling: Smart algorithm finds fair meeting times
• 3D Globe: Visualize global time and participant locations

Tech Stack

• Frontend: Next.js 14, TypeScript, Tailwind CSS, react-globe.gl, Zustand
• Backend: FastAPI, SQLAlchemy 2.0, PostgreSQL
• Real-time: WebSocket

Project Structure

helios/
├── frontend/           # Next.js app
│   ├── app/           # App Router pages
│   ├── components/    # React components
│   ├── hooks/         # Custom hooks
│   ├── lib/           # Utilities
│   └── types/         # TypeScript types
├── backend/           # FastAPI app
│   ├── app/
│   │   ├── routers/   # API endpoints
│   │   ├── services/  # Business logic
│   │   └── utils/     # Utilities
│   └── alembic/       # Database migrations
└── docker-compose.yml # PostgreSQL setup

API Endpoints

Method	Endpoint	Description
POST	/api/sessions	Create session
GET	/api/sessions/{slug}	Get session
POST	/api/sessions/{slug}/participants	Join session
PUT	/api/sessions/{slug}/availability	Set availability
GET	/api/sessions/{slug}/schedule/optimal	Get optimal times
WS	/ws/{slug}	Real-time updates

---

Future Ideas

• Most productive hours tracking
• Study buddy matching for external people
• Social network features for scheduling communities