Project Neo

Ride-sharing app that sources ride requests and offers from messaging platform groups (WhatsApp, Telegram, etc.).

Architecture

┌─────────────────────────────────────────────┐
│  Message Sources (WhatsApp, Telegram, etc.) │
└──────────┬──────────────────────────────────┘
           │
           ▼
┌─────────────────────┐
│      Workers        │
│    (Go Binary)      │
│  - Parse messages   │
│  - Extract rides    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  GraphQL API        │
│    (Go - gqlgen)    │
│  - Queries          │
│  - Mutations        │
│  - Subscriptions    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Supabase (Local)   │
│  - PostgreSQL       │
│  - Realtime         │
│  - Auth             │
└─────────────────────┘
           │
           ▼
┌─────────────────────┬─────────────────────┐
│   Flutter Mobile    │      Web App        │
│   (iOS + Android)   │   (Future Phase)    │
└─────────────────────┴─────────────────────┘

Tech Stack

Service	Language / Framework
Workers	Go 1.25, whatsmeow, go-telegram-bot-api
GraphQL API	Go 1.25, gqlgen, Bun ORM
Shared library	Go 1.25
Database	Supabase (PostgreSQL + Realtime + Auth)
Mobile	Flutter (Dart)
Tooling	Bun, Turborepo, Biome

Prerequisites

• Node.js 24.14.0 via nvm — run nvm use 24.14.0 in each new shell
• Go 1.25+ — golang.org/dl — go version
• Bun 1.3.11+ — bun.sh — bun --version
• Flutter — flutter.dev — flutter --version
• Docker with Docker Compose
• Supabase CLI — supabase --version

Setup

# 1. Clone
git clone <repo-url>
cd project-neo

# 2. Install JS tooling dependencies
bun install

# 3. Environment
cp .env.example .env
# Edit .env — fill in SUPABASE_JWT_SECRET after step 4

# 4. Start Supabase (first run pulls images — ~2 min)
supabase start

# Copy the "JWT secret" from the output above into SUPABASE_JWT_SECRET in .env
# Or run: supabase status

# 5. Apply database migrations
supabase db push

# 6. Start app services
docker compose up -d --build

# 7. Verify
curl http://localhost:8083/health    # → {"status":"ok","service":"workers"}
curl http://localhost:8082/health    # → {"status":"ok","service":"graphql-api"}

Services

Service	Description	Port	README
workers	Connects to WhatsApp/Telegram, parses messages, extracts rides	8083	apps/workers
graphql-api	GraphQL API for rides, matches, groups	8082	apps/graphql-api
shared-go	Shared Go models and repository interfaces	—	packages/shared-go
supabase	Local PostgreSQL + Realtime + Auth + Studio (54323)	54321	supabase
mobile	Flutter mobile app (iOS + Android) — not yet started	—	—

Development Commands

# Run all services in dev mode
bun run dev

# Check formatting (JS/TS + Go)
bun run format:check

# Lint all code
bun run lint

# Build all packages
bun run build

Contributing

This project uses Conventional Commits.

Format: type(scope): subject

Types: feat, fix, docs, style, refactor, perf, build, ci, chore

Scopes: mobile, workers, graphql-api, database, shared, deps, release, docker, ci, docs

Rules:

• Imperative mood: "add" not "added"
• No attribution footers
• Keep commits small and focused