Gantabya

Gantabya is a travel companion app for group trips and city-to-city travel. Plan and share trails, see them on a map, and keep your group coordinated and safe on the road.

https://github.com/user-attachments/assets/fbbb3edc-397b-421f-961c-1315e499b2cd

Features

Available now

• Accounts with email/password sign-in (JWT)
• Trail definition: create, edit and share travel trails on a Mapbox map
• Shareable, server-rendered trail pages (/trails/[id])
• Photo uploads for trails and profiles (Cloudflare R2, with a local-disk fallback in development)
• Realtime updates over socket.io

Coming soon

• Trips and groups
• Live location sharing
• Threaded (Reddit-style) in-app chat
• Notifications
• Weather along trails
• Nearby facilities via OpenStreetMap
• SOS alerts
• Google sign-in
• PWA / offline support

Tech stack

Area	Tech
Frontend	Next.js 15 (App Router), React, TypeScript, Mapbox GL, Vitest
Backend	Node.js 20, Express, TypeScript, socket.io, Vitest
Data	PostgreSQL (Drizzle ORM), Redis (optional: socket.io adapter and shared rate limits)
Storage	Cloudflare R2 (S3-compatible), disk fallback in dev
Hosting	Netlify (frontend), Render (API + Postgres + Key Value)
CI	GitHub Actions, Dependabot

Repo layout

.
├── frontend/              Next.js 15 app (App Router, TypeScript)
│   └── src/app/           routes, incl. trails/[id]
├── server/                Express + socket.io API (TypeScript)
│   ├── src/modules/       feature modules (routes, controllers, models)
│   ├── src/sockets/       socket.io event handlers
│   └── Dockerfile         multi-stage production image
├── docs/
│   └── ARCHITECTURE.md    request flow, auth, storage, realtime
├── .github/               CI workflow and Dependabot config
├── docker-compose.yml     local Postgres + Redis + API
├── render.yaml            Render blueprint (API + Postgres + Key Value)
├── netlify.toml           Netlify build config for the frontend
└── .nvmrc                 Node version (20)

Quick start (Docker)

Requires Docker with Compose v2 and Node 20 (nvm use).

# 1. API + Postgres + Redis on http://localhost:5000
docker compose up --build

# 2. Frontend on http://localhost:3000 (in another terminal)
cd frontend
cp .env.example .env.local   # set NEXT_PUBLIC_MAPBOX_TOKEN
npm install
npm run dev

Compose works without a server/.env. Uploads are stored on disk unless you add R2 keys to server/.env (see Cloudflare R2). Check the API with curl http://localhost:5000/health.

Manual setup (without Docker)

You need Node 20, a PostgreSQL database and, optionally, Redis. Migrations run automatically when the server starts; npm run seed loads demo data.

# API
cd server
cp .env.example .env         # set DATABASE_URL and JWT_SECRET at minimum
npm install
npm run dev                  # http://localhost:5000

# Frontend
cd frontend
cp .env.example .env.local
npm install
npm run dev                  # http://localhost:3000

Environment variables

Server (server/.env)

Variable	Required	Default	Description
DATABASE_URL	yes		Postgres connection string
DATABASE_SSL	no	on in production	Set false for internal/local connections without TLS
JWT_SECRET	yes		Secret for signing JWTs. Use a long random value
NODE_ENV	no	development	development, test or production
PORT	no	5000	HTTP port
JWT_EXPIRES_IN	no	7d	Token lifetime
CLIENT_URL	no		Comma-separated list of allowed frontend origins (CORS and socket.io)
PUBLIC_API_URL	no		Public base URL of this API, used to build /media/* links
R2_ENDPOINT	no	https://cef3bc5e60493c2cde2fa645dac8c39f.r2.cloudflarestorage.com	R2 S3 endpoint
R2_BUCKET	no	gantabya	R2 bucket name
R2_ACCESS_KEY_ID	for R2		R2 API token access key. Without it, uploads go to local disk
R2_SECRET_ACCESS_KEY	for R2		R2 API token secret
RESEND_API_KEY	in production		Resend key for verification and password reset emails. Without it (dev only), emails are printed to the server log
EMAIL_FROM	no	Gantabya <[email protected]>	Sender address. Use an address on a domain verified in Resend; the default test sender only delivers to your own Resend account

Frontend (frontend/.env.local, Netlify env)

Variable	Required	Description
NEXT_PUBLIC_API_URL	yes	Base URL of the API, e.g. http://localhost:5000
NEXT_PUBLIC_MAPBOX_TOKEN	yes	Mapbox public token (pk.…), restricted to your domains

Scripts

Server (cd server)
npm run dev	Start with hot reload (tsx watch)
npm run build	Compile TypeScript to dist/
npm start	Run the compiled server (dist/server.js)
npm run lint / npm run typecheck	ESLint / tsc --noEmit
npm test	Vitest
npm run migrate:uploads	One-off: move legacy uploads to R2

Frontend (cd frontend)
npm run dev	Next.js dev server
npm run build / npm start	Production build / serve it
npm run lint / npm run typecheck	ESLint / tsc --noEmit
npm test	Vitest

Testing

cd server && npm test      # uses PGlite (in-process Postgres), no services needed
cd frontend && npm test

CI (.github/workflows/ci.yml) runs lint, typecheck, test and build for both apps on every push and pull request, then builds the server Docker image.

This is the beginning of the README. Read the rest at the original. Read the full README ↗