# CLAUDE.md

Obsidian: Projects/place

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

josie.place is a real-time location sharing application with map visualizations. It consists of:

- **PWA Frontend** (`web/`) - Static HTML/JS/CSS served by httpd
- **Backend API** (`backend/`) - Crystal HTTP server for real-time location relay
- **Native Apps** - iOS and Android via Capacitor wrapping the PWA

## Architecture

### Components

1. **Share App** (`share.html`, `share.js`) - PWA for broadcasting location. Creates sessions via backend API, uses Capacitor Geolocation for native or Web Geolocation API for browser.

2. **Live Viewer** (`live.html`, `live.js`) - Displays shared location on map. Connects to backend SSE stream at `/api/session/:id/stream`.

3. **Static Maps** (`index.html`, `flights.html`) - Visualization of places and flight routes using Leaflet.js with data from `config.js` and `flights-config.js`.

4. **Backend** (`backend/src/location_server.cr`) - Crystal server handling:
   - `POST /api/session` - Create session (requires auth)
   - `GET/POST /api/session/:id` - Get/update location
   - `GET /api/session/:id/stream` - SSE stream for viewers
   - Sessions auto-expire after 30 minutes of inactivity

### API & URLs

- Frontend: `https://josie.place`
- Live API: `https://live-api.josie.place`
- Session URLs: `https://josie.place/live/<session-id>` (format: `xxxx-xxxx`)

## Development Commands

```bash
# Build web assets for Capacitor
mkdir -p www
cp web/share.html www/index.html
cp web/share.js web/share-sw.js web/share-manifest.json web/style.css www/

# Sync and build iOS
npx cap sync ios
cd ios/App && pod install && xcodebuild -workspace App.xcworkspace -scheme App build

# Build backend container (Crystal)
podman build -t location-server -f backend/Containerfile backend/

# Build frontend container (httpd)
podman build -t josiedotplace -f deploy/Containerfile .
```

## Deployment

- Frontend PWA: Served as ConfigMap by httpd deployment on OCP
- Backend: Container built from `backend/Containerfile`
- iOS: GitHub Actions workflow (`.github/workflows/ios.yml`) builds and uploads to TestFlight
- Environment variable `LOCATION_TOKEN` configures backend auth token

## Key Files

- `web/config.js` - Places map data (copy from `config.js.example`)
- `web/flights-config.js` - Flight routes data
- `capacitor.config.json` - Capacitor config (appId: `live.josie.place`)
- `scripts/generate-flights-config.py` - Generate flight config from data