alex/voyage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add missing project scaffolding

Browse Source
This commit is contained in:
alex
2026-03-08 20:00:11 +00:00
parent 006a28ea0f
commit 3526c963a4
4 changed files with 164 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
AGENTS.md
View File

@@ -1,63 +1,61 @@
# Voyage Agent Project Notes
# Voyage Development Instructions (OpenCode)
This file captures project-local commands and conventions for working in the Voyage repository.
## 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)
## Frontend (SvelteKit)
## 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`.
- Working directory: `frontend/`
- Package manager: `bun`
- Install dependencies: `bun install`
- Dev server: `bun run dev` (Vite dev server; frontend is configured to work with the Django backend in development)
- Build: `bun run build`
- Preview production build: `bun run preview`
- Type check: `bun run check` (`svelte-check`)
- Lint: `bun run lint` (currently runs `prettier --check .`; no ESLint config file is present right now)
- Format: `bun run format` (runs `prettier --write .`)
- Type check (watch mode): `bun run check:watch`
## 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/`
## Backend (Django + DRF)
## Development Commands
- Working directory: `backend/server/`
- Python environment: use project-root `.venv/` if available, otherwise standard Django/Python environment setup
- Install dependencies: `pip install -r requirements.txt`
- Run development server: `python manage.py runserver`
- Apply migrations: `python manage.py migrate`
- Create admin user: `python manage.py createsuperuser`
- Run tests: `python manage.py test`
- Django app locations:
- `backend/server/adventures/`
- `backend/server/achievements/`
- `backend/server/integrations/`
- `backend/server/main/`
- `backend/server/users/`
- `backend/server/worldtravel/`
- Linting: `ruff check .`
- Formatting: `ruff format .`
### Frontend
- `cd frontend && npm run format`
- `cd frontend && npm run lint`
- `cd frontend && npm run check`
- `cd frontend && npm run build`
## Docker Compose Workflows
### Backend
- `docker compose exec server python3 manage.py test`
- `docker compose exec server python3 manage.py migrate`
- Development stack: `docker compose -f docker-compose.dev.yml up`
- Production-like stack: `docker compose up`
- Traefik stack: `docker compose -f docker-compose-traefik.yaml up`
- Rebuild images after changes: add `--build` to the selected command
### Docker
- `docker compose up -d`
- `docker compose down`
## Testing Notes
## 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`
- Frontend tests: no `test` script is currently defined in `frontend/package.json`
- Backend tests: run `python manage.py test` from `backend/server/`
## 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)
## Code Style and Quality
## 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`
- Python style tooling: Ruff (`ruff check .` and `ruff format .`)
- Ruff config location: no `pyproject.toml` or `ruff.toml` was found in this repository, so Ruff defaults (or editor/tooling settings) apply unless added later
- TypeScript/Svelte style tooling: Prettier is configured in `frontend/.prettierrc`; ESLint config files are not currently present
- Commit style: Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`)
## Project Structure Quick Reference
- Frontend source: `frontend/src/`
- Backend apps: `backend/server/<app>/`
- Documentation site: `documentation/` (VitePress)
- Container images:
- `ghcr.io/alex-wiesner/voyage-frontend`
- `ghcr.io/alex-wiesner/voyage-backend`
## Conventions
- Do **not** attempt to fix known test/configuration issues as part of feature work.