# SplatMap

A mobile + web app where users record videos of real-world locations, which are processed into 3D Gaussian Splats and surfaced on a map. At street-level zoom the map transitions into a live 3D splat rendering of that location. Users can create public challenges to send others to specific regions for recording.

## Stack

- **Mobile** — React Native + Vision Camera + Mapbox
- **Web map** — Cesium.js + gaussian-splats-3d
- **Backend** — Django + GeoDjango + PostGIS
- **Queue** — Celery + Redis
- **Splatting pipeline** — COLMAP + gsplat on RunPod
- **Storage** — Wasabi (S3-compatible)
- **Auth** — Authentik (OIDC)
- **Notifications** — Firebase Cloud Messaging

## Prerequisites

- Docker + Docker Compose
- Node.js 20+ (for the web frontend)
- A `.env` file (see below)

## Setup

### 1. Environment

```bash
cp .env.example .env
```

Open `.env` and set at minimum:

```
SECRET_KEY=<long random string>
POSTGRES_PASSWORD=<choose a password>
VITE_CESIUM_ION_TOKEN=<from cesium.com/ion — free tier required>
```

All other values can stay as defaults for local development.

> **Cesium Ion token** — register a free account at https://cesium.com/ion/ and create a token
> with default asset access. Required even in development for imagery and terrain.

### 2. Start the backend

```bash
docker compose up --build
docker compose exec web python manage.py migrate
```

### 3. Start the web frontend

The frontend is not containerised — run it locally alongside Docker.

```bash
cd web
npm install
npm run dev
```

Frontend: http://localhost:5173 (proxies `/api` → Django at :8000)

### 4. Create a superuser

```bash
docker compose exec web python manage.py createsuperuser
```

Admin panel: http://localhost:8000/admin

## Common commands

```bash
# Start all services
docker compose up

# Start in background
docker compose up -d

# Rebuild after dependency changes
docker compose up --build

# Run migrations
docker compose exec web python manage.py migrate

# Make new migrations after model changes
docker compose exec web python manage.py makemigrations

# Open a Django shell
docker compose exec web python manage.py shell

# Open a psql shell
docker compose exec db psql -U splatmap splatmap

# View logs for a specific service
docker compose logs -f web
docker compose logs -f celery

# Stop all services
docker compose down

# Stop and remove volumes (wipes the database)
docker compose down -v
```

## Project structure

```
rcnn/
├── docker-compose.yml
├── .env.example
├── web/                   ← Vite + React frontend
│   ├── package.json
│   ├── vite.config.ts
│   └── src/
│       ├── cesium/        ← Cesium viewer + camera hooks
│       ├── splat/         ← Gaussian splat layer + renderer
│       ├── challenges/    ← Challenge layer + panel + creator
│       ├── api/           ← Typed API wrappers
│       ├── store/         ← Zustand state slices
│       ├── auth/          ← Authentik OIDC
│       └── ui/            ← Shared UI components
└── backend/
    ├── Dockerfile
    ├── manage.py
    ├── requirements/
    │   ├── base.txt
    │   ├── development.txt
    │   └── production.txt
    ├── config/
    │   ├── settings/
    │   │   ├── base.py
    │   │   ├── development.py
    │   │   └── production.py
    │   ├── urls.py
    │   ├── api_urls.py
    │   └── celery.py
    └── apps/
        ├── users/
        ├── splats/
        ├── challenges/
        └── jobs/
```

## API

Base URL: `http://localhost:8000/api/v1/`

All endpoints require a Bearer token from Authentik. In development you can test unauthenticated endpoints directly, or pass a token via:

```
Authorization: Bearer <token>
```

## Running tests

```bash
docker compose exec web pytest
```