# Voyage Development Instructions (OpenCode)

## Project
- **Name**: Voyage
- **Purpose**: Self-hosted travel companion web app (fork of AdventureLog)
- **Stack**: SvelteKit 2 (TypeScript) frontend · Django REST Framework (Python) backend · PostgreSQL + PostGIS · Memcached · Docker · Bun (frontend package manager)

## Architecture Overview
- **API proxy pattern**: Frontend never calls Django directly. All API calls go through `frontend/src/routes/api/[...path]/+server.ts`, which proxies to `http://server:8000`, handles cookies, and injects CSRF behavior.
- **Service ports**:
  - `web` → `:8015`
  - `server` → `:8016`
  - `db` → `:5432`
  - `cache` → internal only
- **Authentication**: Session-based via `django-allauth`; CSRF token from `/auth/csrf/`; mutating requests send `X-CSRFToken`; mobile middleware path supports `X-Session-Token`.

## Codebase Layout
- **Backend**: `backend/server/`
  - Apps: `adventures/`, `users/`, `worldtravel/`, `integrations/`, `achievements/`, `chat/`
- **Frontend**: `frontend/src/`
  - Routes: `src/routes/`
  - Shared types: `src/lib/types.ts`
  - Components: `src/lib/components/`
  - i18n: `src/locales/`

## Development Commands

### Frontend
- `cd frontend && npm run format`
- `cd frontend && npm run lint`
- `cd frontend && npm run check`
- `cd frontend && npm run build`

### Backend
- `docker compose exec server python3 manage.py test`
- `docker compose exec server python3 manage.py migrate`

### Docker
- `docker compose up -d`
- `docker compose down`

## Pre-Commit Checklist
Run in this order:
1. `cd frontend && npm run format`
2. `cd frontend && npm run lint`
3. `cd frontend && npm run check`
4. `cd frontend && npm run build`

## Known Issues (Expected)
- Frontend `npm run check`: **3 type errors + 19 warnings** expected
- Backend tests: **2/3 fail** (expected)
- Docker dev setup has frontend-backend communication issues (500 errors beyond homepage)

## Key Patterns
- i18n: use `$t('key')` for user-facing strings
- API calls: route through proxy at `/api/[...path]/+server.ts`
- Styling: use DaisyUI semantic colors/classes (`bg-primary`, `text-base-content`, etc.)
- Security: handle CSRF tokens via `/auth/csrf/` and `X-CSRFToken`

## Conventions
- Do **not** attempt to fix known test/configuration issues as part of feature work.