voyage/.memory/knowledge/tech-stack.md

title, type, permalink

title	type	permalink
tech-stack	note	voyage/knowledge/tech-stack

Tech Stack & Development

Stack

• Frontend: SvelteKit 2, TypeScript, Bun (package manager), DaisyUI + Tailwind CSS, svelte-i18n, svelte-maplibre
• Backend: Django REST Framework, Python, django-allauth, djmoney, django-geojson, LiteLLM, duckduckgo-search
• Database: PostgreSQL + PostGIS
• Cache: Memcached
• Infrastructure: Docker, Docker Compose
• Repo: github.com/Alex-Wiesner/voyage
• License: GNU GPL v3.0

Development Commands

Frontend (prefer Bun)

• cd frontend && bun run format — fix formatting (6s)
• cd frontend && bun run lint — check formatting (6s)
• cd frontend && bun run check — Svelte type checking (12s; 0 errors, 6 warnings expected)
• cd frontend && bun run build — build (32s)
• cd frontend && bun install — install deps (45s)

Backend (Docker required; uv for local Python tooling)

• docker compose exec server python3 manage.py test — run tests (7s; 6/30 pre-existing failures expected)
• docker compose exec server python3 manage.py migrate — run migrations

Pre-Commit Checklist

1. cd frontend && bun run format
2. cd frontend && bun run lint
3. cd frontend && bun run check
4. cd frontend && bun run build

Environment & Configuration

.env Loading

• Library: python-dotenv==1.2.2 (in backend/server/requirements.txt)
• Entry point: backend/server/main/settings.py calls load_dotenv() at module top
• Docker: docker-compose.yml sets env_file: .env on all services — single root .env file shared
• Root .env: /home/alex/projects/voyage/.env — canonical for Docker Compose setups

Settings File

• Single file: backend/server/main/settings.py (no split/environment-specific settings files)

Server-side Env Vars (from settings.py)

Var	Default	Purpose
SECRET_KEY	(required)	Django secret key
GOOGLE_MAPS_API_KEY	""	Google Maps integration
STRAVA_CLIENT_ID / STRAVA_CLIENT_SECRET	""	Strava OAuth
FIELD_ENCRYPTION_KEY	""	Fernet key for UserAPIKey encryption
OSRM_BASE_URL	"https://router.project-osrm.org"	Routing service
VOYAGE_AI_PROVIDER	"openai"	Instance-level default AI provider
VOYAGE_AI_MODEL	"gpt-4o-mini"	Instance-level default AI model
VOYAGE_AI_API_KEY	""	Instance-level AI API key

Per-User LLM API Key Pattern

LLM provider keys stored per-user in DB (UserAPIKey model, integrations/models.py):

• UserAPIKey table: (user, provider) unique pair → encrypted_api_key (Fernet-encrypted text field)
• FIELD_ENCRYPTION_KEY env var required for encrypt/decrypt
• llm_client.get_llm_api_key(user, provider) → user key → instance key fallback (matching provider only) → None
• No global server-side LLM API keys — every user must configure their own per-provider key via Settings UI (or instance admin configures fallback)

Known Issues

• Docker dev setup has frontend-backend communication issues (500 errors beyond homepage)
• Frontend check: 0 errors, 6 warnings expected (pre-existing in CollectionRecommendationView.svelte + RegionCard.svelte)
• Backend tests: 6/30 pre-existing failures (2 user email key errors + 4 geocoding API mocks)
• Local Python pip install fails (network timeouts) — use Docker