voyage/AGENTS.md

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.