# Project pack: Dawarich @ 2dc26c4

Facts about **Dawarich** 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.

> Dawarich is a self-hosted alternative to Google Timeline. It records your location history from your phone, imports data from Google Takeout and other apps, and shows it on a map with tracks, visited places, statistics and yearly digests. Everything stays on your server.

## Version and source
- Repository: https://github.com/Freika/dawarich
- Pinned commit: `2dc26c40dff1f2e4b6c7e22d78ab5a271c0e8957`. 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/Freika/dawarich/archive/2dc26c40dff1f2e4b6c7e22d78ab5a271c0e8957.zip
- Official docs: https://dawarich.app/docs
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them 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/Freika/dawarich bespoke-dawarich
  cd bespoke-dawarich
  git checkout --detach 2dc26c40dff1f2e4b6c7e22d78ab5a271c0e8957
  # Prepare development requirements and local configuration first.
  bundle install
  npm install
  bin/rails db:setup
  bin/dev
  ```

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
  Follow the self-hosting guide at https://dawarich.app/docs/tutorials/self-hosting, which provides the docker-compose.yml file.
  ```

- Needs: Docker with PostGIS and Redis; Ruby 3.4 and Node 22 for development
- Develop: `bin/dev`
- Test: `bundle exec rspec`
- Check/lint: `bundle exec rubocop`
- Stack: ruby, javascript (Ruby on Rails, Hotwire, Leaflet, Sidekiq). Difficulty for a non-developer with an AI: **moderate**. A conventional Rails app with background jobs. Most personal use is configuration and imports; features follow the usual Rails structure.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **imports** [settings]: Bring your old location history in. → `Imports page (Google Takeout, GPX, GeoJSON, Owntracks)`
- **visits-and-places** [settings]: Define places like Home and Work and let it detect visits. → `Map → Visits, Places, Areas`
- **api** [extend]: Send points from scripts and shortcuts. → `/api/v1 and the API key in Settings`
- **stats-and-digests** [code]: New statistics and yearly digests. → `app/services and app/views/stats`
- **map-layers** [code]: Map styles, layers and controls. → `app/javascript`

## Must keep working
- Rails migrations. Add new ones; never edit old ones.
- Import parsers, since users depend on them.
- API key authentication and sharing permissions.

## Staying updatable
Prefer imports, settings and the API. Add code as new services and views, and follow the project's CONTRIBUTING guide.

## Data, costs and safety
- Personal data: **yes**. Stored in: A Postgres database with PostGIS plus a storage volume for imports. This is a precise record of where you have been. Use HTTPS, a strong password and encrypted backups.
- Service: Reverse geocoding (Photon or Geoapify) (optional, free self-hosted or free tier): Turn coordinates into place names.
- Service: Phone tracking app (OwnTracks, GPSLogger or the Dawarich app) (required, free): Sends your location to the server.
- Setting `SECRET_KEY_BASE` (**secret**: the person enters it themselves, never in chat): Rails secret used to sign sessions. Never paste it into an AI chat.
- Setting `DATABASE_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password.
- Setting `APPLICATION_HOSTS`: The address people use to reach Dawarich.
- Location history reveals where you live and work. Never run it unprotected on the public internet.
- Don't paste your API key into an AI chat.
- Encrypt backups.

---

# Customising Dawarich

Dawarich is a Rails app. If you know Rails, the structure is conventional, with Sidekiq jobs for heavy work.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Controllers and views | app/controllers/ and app/views/ |
| Models | app/models/ |
| Services (imports, stats, geocoding) | app/services/ |
| Background jobs | app/jobs/ |
| Front-end scripts and map code | app/javascript/ |
| Migrations | db/migrate/ |
| Agent guidance | AGENTS.md and CLAUDE.md |

## Use the gentlest change first

1. **Settings (no code):** imports, visits, places, geocoding and sharing.
2. **Extend:** API scripts and automations.
3. **Code:** new services, views and stats.

## Recipes

- **New statistic:** add a service in `app/services`, call it from the stats controller, and render it in the stats view.
- **New import format:** add a parser under `app/services/<format>` following the existing ones, with sample files in specs.

## Running and checking your changes

- `bundle exec rspec` for the area you changed.
- `bundle exec rubocop` before you finish.
- Import a small sample file and check the map and stats.

## Pitfalls

- Don't use your real location data in tests. Use generated samples.
- Background jobs run in Sidekiq. Start it when testing imports.

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