# nodes

id: adventurelog-application
name: AdventureLog Application
kind: feature
why: Main application entry point - all other concepts are subsystems of this travel companion app
created_at: 2026-03-06 10:45:33
updated_at: 2026-03-06 10:45:33
summary:
Full-stack travel companion application for tracking adventures, planning trips, and sharing experiences. Stack: Django + PostGIS backend, SvelteKit + DaisyUI + MapLibre frontend. Features location tracking, itinerary planning, world travel stats, and integrations with Immich/Strava/Wanderer. Version: v0.12.0. GPL-3.0 license.

file_refs:
["README.md","backend/server/main/settings.py","backend/server/adventures/models.py","frontend/src/lib/types.ts"]


id: location-system
name: Location System
kind: module
why: Primary feature - users track visited/planned locations with rich metadata
created_at: 2026-03-06 10:45:40
updated_at: 2026-03-06 10:45:40
summary:
Core location tracking with Location (name, lat/lng 9,6 precision, category, tags, rating, price MoneyField USD, link, is_public, city/region/country FKs), Visit (start/end_date, timezone from TIMEZONES, notes, activities[]), Trail (link to AllTrails/Komoot OR wanderer_id), Activity (GPX file, sport_type, distance meters, elevation, speed m/s, calories, Strava sync), Category (name lowercase unique per user, display_name, icon default 🌍). ContentImage/ContentAttachment via GenericForeignKey attach to any content. Auto-geocodes on Location save in background thread.

file_refs:
["backend/server/adventures/models.py:1-200","backend/server/adventures/views/location_view.py","frontend/src/lib/components/locations/","frontend/src/routes/locations/"]


id: collection-system
name: Collection System
kind: module
created_at: 2026-03-06 10:45:46
updated_at: 2026-03-06 10:45:46
summary:
Trip planning with Collection (name, description, is_public, start/end_date, is_archived, shared_with M2M, locations M2M, primary_image FK, link). Itinerary: CollectionItineraryDay (date, name, description - unique per collection+date), CollectionItineraryItem (GenericForeignKey to Visit/Transportation/Lodging/Note/Checklist, date XOR is_global, order - unique per day/global). Collaborators via CollectionInvite. Status computed: 'folder'|'upcoming'|'in_progress'|'completed', days_until_start. Validation: public collections cannot have private locations.

why:
Core planning feature - organize trips with locations, transport, lodging, notes, checklists in day-by-day itinerary

file_refs:
["backend/server/adventures/views/collection_view.py","backend/server/adventures/views/itinerary_view.py","frontend/src/lib/components/collections/","frontend/src/routes/collections/"]


id: world-travel-tracking
name: World Travel Tracking
kind: module
why: Gamification feature - track countries/regions visited with visual map progress
created_at: 2026-03-06 10:45:51
updated_at: 2026-03-06 10:45:51
summary:
Country/region/city tracking from dr5hn/countries-states-cities-database v3.0. Models: Country (name, country_code, subregion, flag_url, capital, num_regions, num_visits, lat/lng), Region (name, country FK, lat/lng, num_cities), City (name, lat/lng, region FK). User progress: VisitedRegion, VisitedCity (user FK, region/city FK, lat/lng, name). Download command: python manage.py download-countries. Sync command: sync_visited_regions auto-matches locations to regions.

file_refs:
["backend/server/worldtravel/","frontend/src/routes/worldtravel/","backend/server/adventures/management/commands/sync_visited_regions.py"]


id: integrations
name: Integrations
kind: module
why: Extends functionality with photo management, activity tracking from fitness apps, trail databases
created_at: 2026-03-06 10:45:57
updated_at: 2026-03-06 10:45:57
summary:
External service connections: (1) ImmichIntegration (server_url, api_key, copy_locally) - photo search/albums via /api/integrations/immich/{id}/search?query=|date=, image proxy at /api/integrations/immich/{id}/get/{immich_id}. (2) StravaToken (access_token, refresh_token, expires_at, athlete_id) - OAuth at /api/integrations/strava/authorize→callback, activity sync creates Activity models from GPX. (3) WandererIntegration (server_url, api_key, username) - trail import via wanderer_id creates Trail models. ContentImage can use immich_id XOR local image file.

file_refs:
["backend/server/integrations/views/immich_view.py","backend/server/integrations/views/strava_view.py","backend/server/integrations/wanderer_services.py"]


id: geocoding-service
name: Geocoding Service
kind: module
why: Essential for location search and automatic region/city assignment on location save
created_at: 2026-03-06 10:46:03
updated_at: 2026-03-06 10:46:03
summary:
Location search and reverse geocoding. search(query) tries Google Places API (New) first if GOOGLE_MAPS_API_KEY set, falls back to OpenStreetMap Nominatim. Returns: lat, lon, name, display_name, type, category, importance, addresstype, powered_by. reverse_geocode(lat, lon, user) extracts ISO 3166-2 codes, matches Region/City in DB, checks VisitedRegion/VisitedCity status. Returns: region_id, region, country, country_id, region_visited, city_visited, display_name, city, city_id, location_name. Error handling returns {\"error\": \"user-friendly message\"} for timeouts, connection errors, HTTP errors.

file_refs:
["backend/server/adventures/geocoding.py","backend/server/adventures/views/reverse_geocode_view.py"]


id: authentication-system
name: Authentication System
kind: module
why: User accounts, sharing, collaboration, and security foundation
created_at: 2026-03-06 10:46:10
updated_at: 2026-03-06 10:46:10
summary:
Django AllAuth with custom user model (AUTH_USER_MODEL='users.CustomUser'). Features: email verification, password reset, MFA (allauth.mfa), social auth (GitHub, OpenID Connect), invite-only via invitations app (DISABLE_REGISTRATION env var). Custom adapters: CustomAccountAdapter, CustomSocialAccountAdapter. Custom backend: NoPasswordAuthBackend for passwordless option. HEADLESS_FRONTEND_URLS for email links (confirm_email, reset_password, signup). SESSION_COOKIE_SAMESITE='Lax', dynamic cookie domain via publicsuffix2. Custom middleware: XSessionTokenMiddleware, DisableCSRFForSessionTokenMiddleware.

file_refs:
["backend/server/users/views.py","backend/server/users/models.py","frontend/src/routes/login/","frontend/src/routes/signup/","frontend/src/routes/settings/+page.svelte"]


id: frontend-application
name: Frontend Application
kind: module
why: User interface - SvelteKit SPA with rich map interactions and collaborative features
created_at: 2026-03-06 10:46:16
updated_at: 2026-03-06 10:46:16
summary:
SvelteKit frontend with TailwindCSS + DaisyUI (dim theme). MapLibre via svelte-maplibre for interactive maps. Routes: /dashboard (stats summary), /locations (list/[id]), /collections (list/[id] with itinerary planner), /map (all locations with add by click), /worldtravel (countries/[id]/[id] for regions/cities), /transportations/[id], /lodging/[id], /calendar, /search, /settings (integrations, profile). i18n: 20+ locales in frontend/src/locales/*.json via Weblate. Key components: LocationSearchMap, CollectionItineraryPlanner, CollectionMap, FullMap, ImageManagement, CategoryDropdown, NoteModal, ChecklistModal, ShareModal, TOTPModal.

file_refs:
["frontend/src/routes/","frontend/src/lib/components/","frontend/src/lib/types.ts","frontend/src/lib/index.ts"]


id: travel-items
name: Travel Items
kind: module
why: Comprehensive trip planning - not just locations but flights, hotels, notes, and checklists
created_at: 2026-03-06 10:46:23
updated_at: 2026-03-06 10:46:23
summary:
Planning content types: (1) Transportation (type: car/plane/train/bus/boat/bike/walking/other, flight_number, from/to_location, origin/dest lat/lng, start/end_code for airports, date/end_date, start/end_timezone, price MoneyField, distance km, collection FK). (2) Lodging (type: hotel/hostel/resort/bnb/campground/cabin/apartment/house/villa/motel/other, check_in/out, timezone, reservation_number, price, lat/lng, location, collection FK). (3) Note (name, content, links ArrayField URL, date, collection FK). (4) Checklist (name, date, ChecklistItem children with is_checked, collection FK). All support ContentImage/ContentAttachment, is_public flag.

file_refs:
["backend/server/adventures/views/transportation_view.py","backend/server/adventures/views/lodging_view.py","backend/server/adventures/views/note_view.py","backend/server/adventures/views/checklist_view.py"]


id: voyage-project
name: Voyage Project
kind: module
why: Fork of AdventureLog with intent to make custom changes under the Voyage brand.
created_by_task: Full project rename from AdventureLog to Voyage
created_at: 2026-03-06 11:02:25
updated_at: 2026-03-06 11:02:25
summary:
Voyage is a fork of AdventureLog — a full-stack travel logging application. Stack: Django + PostGIS backend, SvelteKit + DaisyUI + MapLibre frontend. License: GPL-3.0. Docker images: ghcr.io/seanmorley15/voyage-frontend and voyage-backend. The project was fully renamed from AdventureLog to Voyage in March 2026, replacing all 7 case variants (AdventureLog, adventurelog, Adventurelog, ADVENTURELOG, AdventUrelog, AdventureLOG, adventure-log, adventure_log) across ~102 files, and renaming all asset/script files (brand/voyage.svg, brand/voyage.png, frontend/static/voyage.svg, install_voyage.sh, backend/server/voyage.txt, etc.).

file_refs:
["frontend/package.json","backend/server/main/settings.py","docker-compose.yml","brand/voyage.svg","brand/voyage.png","frontend/static/voyage.svg","install_voyage.sh"]


