# Project pack: AdventureLog @ 5673ef5

Facts about **AdventureLog** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> AdventureLog is a self-hosted travel tracker. You log places you have visited with photos, notes and dates, see them on a world map with countries and regions filled in, and plan upcoming trips with itineraries and shared collections. It is designed for travellers who want to keep their own travel history.

## Version and source
- Repository: https://github.com/seanmorley15/AdventureLog
- Pinned commit: `5673ef5bb5aaa96081bc250ef1d16da8b45977e3`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/seanmorley15/AdventureLog/archive/5673ef5bb5aaa96081bc250ef1d16da8b45977e3.zip
- Official docs: https://adventurelog.app/docs/intro/adventurelog_overview.html
- Live demo: https://demo.adventurelog.app/signup. Shared demo. Don't enter real data.
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/seanmorley15/AdventureLog bespoke-adventurelog
  cd bespoke-adventurelog
  git checkout --detach 5673ef5bb5aaa96081bc250ef1d16da8b45977e3
  # Prepare development requirements and local configuration first.
  cp .env.example .env
  docker compose up -d
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  git clone https://github.com/seanmorley15/AdventureLog adventurelog-run
  cd adventurelog-run
  cp .env.example .env
  # edit .env and set a strong POSTGRES_PASSWORD and the public URL
  docker compose up -d
  # then open http://localhost:8015
  ```

- Needs: Docker, or Node 22 and Python 3.12 with PostGIS for development
- Develop: `docker compose up -d`
- Stack: typescript, python (SvelteKit, Django, Django REST Framework, Tailwind, Leaflet). Difficulty for a non-developer with an AI: **moderate**. A SvelteKit front end and a Django back end with a PostGIS database. Familiar structure; the map and region data add some weight.

## Customisation points (settings → extend → code)
- **visits-and-collections** [settings]: Log places, group them into trips and share them. → `In the app, under Adventures and Collections`
- **categories** [settings]: Your own types of places such as Beach, Museum or Hike. → `Settings → Categories`
- **integrations** [extend]: Connect photo libraries and other sources. → `Settings → Integrations and the documentation`
- **frontend** [code]: Screens and map layers. → `frontend/src`
- **backend** [code]: New models and API endpoints. → `backend/server`

## Must keep working
- Django migrations. Add new ones; never edit old ones.
- Sharing permissions for collections.
- Photo upload handling.

## Staying updatable
Prefer settings and collections. Add code as new Django apps or Svelte routes so merging stays easy.

## Data, costs and safety
- Personal data: **yes**. Stored in: A Postgres database plus a media folder for photos. Travel dates and locations are personal. Back up the database and the media volume.
- Service: Map tiles and geocoding (OpenStreetMap-based) (optional, free): Show maps and find places.
- Service: Email (SMTP) (optional, usually free to a few dollars): Invitations and password resets.
- Setting `POSTGRES_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password. Never paste it into an AI chat.
- Setting `SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Django secret key. Never paste it into an AI chat.
- Setting `PUBLIC_URL`: The address people use to reach AdventureLog.
- Location history is sensitive. Share collections only with people you trust.
- Keep SECRET_KEY and database passwords out of Git and chats.

---

# Customising AdventureLog

AdventureLog is a SvelteKit app talking to a Django API. If you know either framework, the layout will be familiar.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Screens and components | frontend/src/ |
| Django apps, models and API | backend/server/ |
| Database and geodata setup | backend/ and docker/ |
| Docs | documentation/ |
| Kubernetes | k8s/ |

## Use the gentlest change first

1. **Settings (no code):** categories, collections, sharing and language.
2. **Extend:** integrations from the settings page.
3. **Code:** Svelte pages and Django models.

## Recipes

- **New field on adventures:** add it to the model, create a Django migration, include it in the serializer, then add it to the form and detail page in `frontend/src`.
- **New page:** add a route folder under `frontend/src/routes` and link it from the navbar.

## Running and checking your changes

- Start with Docker, log a place with a photo and check it on the map.
- Run the Django tests and the Svelte checks for the area you changed.
- Create a collection and share it with a second user.

## Pitfalls

- Don't edit old migrations.
- Set the public URL correctly or logins and images may fail.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/adventurelog/5673ef5/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/adventurelog/5673ef5/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/adventurelog/5673ef5/r2/SKILL.md)