62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
# 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.
|