From 370a50dcb2899d3fc29cf7a4d00d1c6f9fda3cac Mon Sep 17 00:00:00 2001
From: alex <misc@wiesner.com.br>
Date: Fri, 6 Mar 2026 14:34:16 +0000
Subject: [PATCH] chore: add missing project scaffolding

---
 AGENTS.md            | 63 ++++++++++++++++++++++++++++++++++++++++++++
 docs/architecture.md | 14 ++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 docs/architecture.md

diff --git a/AGENTS.md b/AGENTS.md
index e69de29b..1396ea92 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,63 @@
+# Voyage Agent Project Notes
+
+This file captures project-local commands and conventions for working in the Voyage repository.
+
+## Frontend (SvelteKit)
+
+- Working directory: `frontend/`
+- Package manager: `pnpm`
+- Install dependencies: `pnpm install`
+- Dev server: `pnpm dev` (Vite dev server; frontend is configured to work with the Django backend in development)
+- Build: `pnpm build`
+- Preview production build: `pnpm preview`
+- Type check: `pnpm check` (`svelte-check`)
+- Lint: `pnpm lint` (currently runs `prettier --check .`; no ESLint config file is present right now)
+- Format: `pnpm format` (runs `prettier --write .`)
+- Type check (watch mode): `pnpm check:watch`
+
+## Backend (Django + DRF)
+
+- 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 .`
+
+## Docker Compose Workflows
+
+- 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
+
+## Testing Notes
+
+- Frontend tests: no `test` script is currently defined in `frontend/package.json`
+- Backend tests: run `python manage.py test` from `backend/server/`
+
+## Code Style and Quality
+
+- 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`
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..bee808af
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,14 @@
+# Architecture
+
+Voyage is a full-stack travel companion application (a fork of AdventureLog) with a SvelteKit + TypeScript frontend, a Django + Django REST Framework backend, and a PostgreSQL/PostGIS database, with supporting documentation in VitePress and containerized development/deployment via Docker Compose.
+
+## TODO
+
+This is a stub and must be expanded with:
+
+- System diagrams
+- Data flow
+- Component relationships
+- API design
+- Database schema overview
+- Deployment topology