If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Freika/dawarich shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 2d ago
• AGPL-3.0 licensed
• CI configured
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Freika/dawarich repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Freika/dawarich.

What it runs against: a local clone of Freika/dawarich — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Freika/dawarich | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Freika/dawarich. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Freika/dawarich.git
#   cd dawarich
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Freika/dawarich and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Freika/dawarich(\\.git)?\\b" \\
  && ok "origin remote is Freika/dawarich" \\
  || miss "origin remote is not Freika/dawarich (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "Procfile.dev" \\
  && ok "Procfile.dev" \\
  || miss "missing critical file: Procfile.dev"
test -f ".env.development" \\
  && ok ".env.development" \\
  || miss "missing critical file: .env.development"
test -f "app/assets/stylesheets/application.tailwind.css" \\
  && ok "app/assets/stylesheets/application.tailwind.css" \\
  || miss "missing critical file: app/assets/stylesheets/application.tailwind.css"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Freika/dawarich"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Dawarich is a self-hosted Rails web application that replaces Google Timeline by tracking, storing, and visualizing personal location history. It ingests location data from multiple sources (Google Maps Timeline, OwnTracks, GPX, GeoJSON, native iOS/Android apps), displays it on interactive maps, detects trips, generates travel analytics, and integrates with photo services like Immich and Photoprism to geolocate images. Standard Rails monolith: app/ contains MVC layers (models, controllers, views), app/assets/ holds Tailwind CSS builds and images, Procfile variants (dev, production, prometheus) define service startup. Location data flows into models (implied by feature set), processed by background jobs (Sidekiq via Procfile), and surfaced via views. JavaScript (~1.1MB) suggests some client-side interactivity; Biome linting indicates modern JS tooling.

Privacy-conscious individuals who want full control over their location history without sending data to Google; self-hosting enthusiasts comfortable running Docker containers; families wanting to share location data privately within their own infrastructure; developers building location-aware features who need a self-contained, auditable backend.

Actively developed and reasonably mature for self-hosting: the project has established CI/CD via CircleCI and GitHub Actions, comprehensive Docker setup, structured Rails conventions, and a Discord community. However, the README explicitly warns against automatic updates and notes 'under active development' with 'frequent updates, bugs, and breaking changes'—treat as production-ready but require careful update management.

Single-maintainer (freika) concentration risk evident from repo structure. Frequent breaking changes require reading release notes before updates (explicitly warned in README). Large Ruby dependency footprint (Gemfile.lock) without visible dependency audit tooling. Requires PostgreSQL, Redis, and Sidekiq coordination which adds operational complexity; check for stale issues around database migrations and job queue reliability.

Actively maintained with recent CI workflows for Biome (JavaScript linting), RuboCop (Ruby linting), and automated Docker builds via build_and_push.yml. Dependabot enabled for dependency updates. Release notifications workflow suggests frequent versioning. CLAUDE.md and CONTRIBUTING.md indicate organized contribution guidelines—project is in active feature development and bug fixes.

git clone https://github.com/Freika/dawarich.git
cd dawarich
cp .env.development .env
bundle install
bundle exec rake db:setup
bundle exec foreman start -f Procfile.dev

Access at http://localhost:3000 (Rails), with Tailwind watcher and presumably frontend assets served.

Daily commands: Development (with file watchers): bundle exec foreman start -f Procfile.dev (runs Rails, Tailwind watcher, JS bundler). Production: bundle exec foreman start -f Procfile.production. With Prometheus: bundle exec foreman start -f Procfile.prometheus.dev. Ensure .env.development / .env is configured with database URL, Redis URL, and any secret keys before running.

• Gemfile — Ruby dependencies declaration—all backend gems and versions are pinned here; essential for understanding the tech stack and compatibility.
• Procfile.dev — Development process definition—shows how the Rails app, frontend build, and other services are orchestrated; critical for local setup.
• .env.development — Development environment configuration template—defines all required env vars for features like map tiles, location sources, and integrations.
• app/assets/stylesheets/application.tailwind.css — Primary stylesheet using Tailwind CSS—the UI foundation for the entire frontend, pulled into all views.
• .github/workflows/ci.yml — Continuous integration pipeline—defines test suites, linters (RuboCop, Biome), and quality gates that gate all commits.
• Rakefile — Rails task definitions—contains database migrations, seed tasks, and automated maintenance jobs that are central to deployment.
• app.json — Heroku/platform configuration—declares the app's runtime, buildpacks, environment variables, and add-ons; governs deployment.

• Location Agent (e.g., Google Timeline Sync, OwnTracks Listener) — Polls or listens for location updates from external sources; validates and stores raw location points in DB.

Add a New Location Data Source (Agent)

1. Review AGENTS.md to understand agent architecture and protocols (AGENTS.md)
2. Add agent environment variables to .env.development (e.g., GOOGLE_API_KEY, OWNTRACKS_URL) (.env.development)
3. Implement agent class in app/services (typically a Location sync service) that fetches data and stores in DB (app)
4. Register agent in Rakefile as a scheduled task or background job (Rakefile)

Add a New Map Feature or Timeline Visualization

1. Create or extend MapLibre-specific stylesheet for the new UI component (app/assets/stylesheets/maps_maplibre.css)
2. Add view template or partial that uses Tailwind classes from application.tailwind.css (app/assets/stylesheets/application.tailwind.css)
3. Implement controller action or Stimulus controller in app/javascript to handle interactions (app)
4. Test the feature in dev container using Procfile.dev to ensure asset pipeline works (Procfile.dev)

Set Up Local Development Environment

1. Follow the complete setup steps in DEVELOPMENT.md (DEVELOPMENT.md)
2. Copy .env.development and configure required API keys, database, and service URLs (.env.development)
3. Use devcontainer setup with provided docker-compose for all services (.devcontainer/docker-compose.yml)
4. Run 'foreman start -f Procfile.dev' to boot Rails, Vite, and background workers (Procfile.dev)

Add a Code Quality or Linting Rule

1. Update RuboCop config to add or modify Ruby linting rules (.rubocop.yml)
2. For JavaScript/TypeScript, configure Biome in the root or .biomerc.json (.github/workflows/biome.yml)
3. Add rule verification step in CI workflow to block PRs that violate new rules (.github/workflows/ci.yml)

• Rails (Ruby) — Rapid web development with built-in ORM (ActiveRecord), migrations, and admin tooling; ideal for self-hosted location-tracking app with complex queries.
• PostgreSQL — PostGIS extension enables geospatial queries (distance, clustering, bounds); essential for efficient location history analysis and trip detection.
• MapLibre GL / Leaflet — Client-side map rendering libraries compatible with self-hosted tile servers; no Google Maps dependency preserves privacy.
• Tailwind CSS — Utility-first CSS framework reduces custom stylesheet maintenance; rapid UI iteration for dashboard and timeline views.
• Docker & Docker Compose — Self-hosting requires easy multi-service orchestration (Rails, DB, cache, background jobs); Docker ensures reproducible deployments.
• GitHub Actions CI/CD — Automated testing, linting (RuboCop, Biome), and build verification on every commit; gates quality before merge.

• Rails monolith rather than microservices

  • Why: Self-hosted scope and team size favor simplicity; reduces operational complexity for end-users.
  • Consequence: Vertical scaling limitations; location sync and processing happen in same app instance. Mitigation: background jobs (Sidekiq/DelayedJob) decouple sync from web requests.

• MapLibre GL instead of Google Maps API

  • Why: Privacy-first positioning; users want offline/local tile data and no Google tracking.
  • Consequence: Requires setup of tile server (e.g., OpenStreetMap, self-hosted); higher operational burden than managed Google Maps.

• PostgreSQL + PostGIS instead of specialized geo DB (MongoDB, CouchDB)

  • Why: Strong ACID guarantees for location history integrity; excellent geospatial query performance with PostGIS.
  • Consequence: Requires additional PostGIS extension; schema migrations are less flexible than NoSQL.

• Tailwind CSS instead of component library (Bootstrap, Material)

  • Why: Smaller bundle, faster iteration, minimal CSS bloat for a single-product dashboard.
  • Consequence: Less out-of-box component polish; requires custom design decisions per page.

• Real-time collaborative location sharing at millisecond latency (eventual consistency is acceptable).
• Supporting unlimited historical data imports (memory and query optimization focus on recent 12–24 months).
• Native mobile app (web-only; mobile clients are browsers or third-party agents).
• Commercial SaaS hosting (project is self-hosted; cloud version is separate paid service).
• Blockchain or distributed ledger storage (centralized self-hosted database).

Database migrations required: First run bundle exec rake db:setup or migrations will fail silently in some contexts; check .env for DATABASE_URL pointing to valid PostgreSQL. Redis dependency: Sidekiq background jobs require Redis running; docker-compose.yml in .devcontainer/ handles this, but bare rails s will fail without Redis. Tailwind compilation: CSS in app/assets/builds/tailwind.css is pre-built; running Procfile.dev with the watcher is essential or style changes won't appear. Ruby version constraint: .ruby-version file exists—use rbenv or rvm to match, mismatches cause cryptic gem compilation errors. Frequent breaking changes: The README explicitly warns not to auto-update; check CHANGELOG.md and release notes before upgrading database schema or dependency versions.

• Geofencing and Trip Detection — Core feature of Dawarich: clustering location points into meaningful 'trips' requires understanding distance metrics (haversine), temporal gaps, and state-machine logic to distinguish between stops and movements
• Haversine Formula — Dawarich must calculate distances between GPS coordinates to cluster locations; the Haversine formula computes great-circle distance on a sphere and is likely used internally
• Background Job Processing with Sidekiq — Location imports and trip detection are slow operations; Dawarich uses Sidekiq (visible in Procfile) to avoid blocking the web server, making async job scheduling critical to understand
• GeoJSON and GPX Formats — Dawarich accepts location data in multiple formats (GPX, GeoJSON); understanding these interchange formats is essential for adding new import sources or debugging data loss
• Timezone-Aware Timestamps — Location data often arrives with incomplete timezone info; Dawarich must handle UTC conversion, daylight saving time, and user-local display without corrupting trip boundaries
• Rails Background Jobs (Sidekiq + Redis) — Data imports and analytics calculations run asynchronously via Sidekiq; understanding job retries, dead-letter queues, and Redis persistence is crucial for reliability
• Map Tile Rendering (Likely Leaflet.js) — Dawarich visualizes locations on interactive maps; the frontend likely uses Leaflet or similar to render tiles and overlay GPS traces efficiently

• owntracks/frontend — Complementary UI for OwnTracks location tracking (one of Dawarich's data sources); useful to understand expected coordinate/timestamp formats
• immich-app/immich — Dawarich integrates with Immich for geotagged photo visualization; studying Immich's location API helps understand the integration points
• photoprism/photoprism — Another photo management integration target for Dawarich; review to understand how location data flows into external systems
• home-assistant/core — Dawarich supports Home Assistant as a location source; checking Home Assistant's location schema ensures import compatibility
• nextcloud/server — Dawarich is a self-hosted alternative analogous to Nextcloud's photo + location features; community often deploys both together

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for end-to-end (E2E) testing with Playwright or Cypress

The repo has CircleCI config (.circleci/config.yml) and multiple GitHub Actions workflows (biome.yml, rubocop.yml, ci.yml), but there's no dedicated E2E testing workflow. Given that Dawarich is a Rails app with complex map and location tracking features (evidenced by screenshots showing Map, Insights, Family, Trips, Stats views), adding E2E tests would catch UI regressions. This is high-value because location tracking apps are sensitive to broken user flows.

• [ ] Create .github/workflows/e2e.yml with Playwright or Cypress setup
• [ ] Add E2E test fixtures for core user journeys: login → upload location data → view map → filter by date range
• [ ] Configure workflow to run on PR and main branch pushes, reporting results back to PR
• [ ] Document E2E testing setup in DEVELOPMENT.md (currently exists but likely lacks E2E guidance)

Add unit/integration tests for location data processing pipeline

The repo has .rspec config indicating RSpec usage, but the file structure shows app/assets and app/controllers likely exist without visible test coverage in this listing. Location history apps require robust data validation (duplicate filtering, timezone handling, coordinate accuracy). This PR would add specs for the core domain logic that processes raw location points into meaningful trips and insights.

• [ ] Create spec/services/ directory with tests for location data import/parsing (e.g., spec/services/location_import_service_spec.rb)
• [ ] Add specs for trip detection logic (e.g., grouping nearby points into trips with time-based clustering)
• [ ] Add specs for coordinate validation and duplicate detection
• [ ] Ensure coverage for edge cases: null timestamps, invalid coordinates, timezone conversions

Add Docker Compose health checks and monitoring workflow for self-hosted deployments

The repo has .devcontainer/docker-compose.yml and Procfile.production, but no explicit health check configuration or monitoring setup documentation. Self-hosted users need confidence that Dawarich services are running correctly. Adding health checks to docker-compose.yml and a monitoring GitHub Actions workflow (like checking container status) would improve deployment reliability and provide users with better debugging tools.

• [ ] Update .devcontainer/docker-compose.yml and create docker-compose.production.yml with healthcheck directives for all services (Rails app, database, Redis if used)
• [ ] Create .github/workflows/docker_health_check.yml to validate Docker Compose configuration and simulate startup
• [ ] Add health check endpoints documentation to DEVELOPMENT.md or new DEPLOYMENT.md section
• [ ] Document how self-hosted users can verify service health using the same checks

• Add test coverage for location import parsers: app/models/ likely has GPX/GeoJSON parsing logic but spec/ may lack comprehensive tests for edge cases (malformed coordinates, missing timestamps, timezone handling). Write RSpec examples covering import failures.: Core feature, high impact, well-scoped to a single module
• Document the trip detection algorithm: No visible ALGORITHM.md or inline comments explaining how locations cluster into 'trips'—write a design doc in docs/ (if it exists) or a detailed comment block in the trip model, explaining distance/time thresholds.: Improves maintainability and helps future contributors tune the heuristic
• Add GitHub Actions workflow for end-to-end testing with Docker Compose: Current workflows test Ruby/JS linting and units, but no E2E tests of the full app stack (Rails + PostgreSQL + Redis). Create a workflow that spins up .devcontainer/docker-compose.yml, seeds data, and runs Capybara tests.: Catches integration bugs early, especially around job queue processing and database transactions

• High · Missing Dependency Analysis — Gemfile, Gemfile.lock. Unable to perform comprehensive dependency vulnerability scanning. The Gemfile and Gemfile.lock files are referenced but not provided for analysis. This prevents identification of known CVEs in Ruby dependencies. Fix: Provide dependency files for analysis. Implement automated dependency scanning using tools like Dependabot (already configured), Bundler Audit, or Snyk. Review GitHub security alerts regularly.
• High · Potential Exposed Environment Variables — .env.development, .env.test, .gitignore. The repository contains multiple .env files (.env.development, .env.test) which may contain sensitive credentials. Even with .gitignore, there's risk of accidental commits or exposure of example values. Fix: Use .env.example templates without actual secrets. Never commit .env files. Implement pre-commit hooks to prevent secret commits. Consider using environment-specific secret management (AWS Secrets Manager, HashiCorp Vault).
• High · Location Data Privacy Exposure — app structure (database layer not visible). As a location history tracker, the application stores sensitive geolocation data. Without explicit visibility into encryption at rest, data minimization practices, and access controls, this poses significant privacy risks. Fix: Implement encryption at rest for all location data. Add encryption in transit (HTTPS/TLS). Implement granular access controls. Add data retention policies. Consider GDPR/CCPA compliance measures. Audit data access logs.
• Medium · Potential XSS Vulnerabilities in Rails Application — app/assets, app/views (not visible in provided structure). The presence of multiple stylesheets and JavaScript handling (app/assets/builds/) in a Rails app suggests dynamic content rendering. Without reviewing controller/view code, there's risk of stored/reflected XSS. Fix: Use Rails XSS protection (enabled by default). Always use content_tag and sanitize helpers. Implement Content Security Policy (CSP) headers. Regular security audits of view templates.
• Medium · Missing Security Headers Configuration — config files (not visible), middleware. No visible configuration for security headers (HSTS, CSP, X-Frame-Options, X-Content-Type-Options) in the provided file structure. Fix: Configure secure_headers gem or middleware to enforce: HSTS, CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy. Implement in config/initializers/secure_headers.rb
• Medium · Docker Image Security Not Fully Visible — .devcontainer/Dockerfile, production Docker setup. Dockerfile in .devcontainer is provided but production Dockerfile and security practices (image scanning, non-root user, minimal base images) are not visible. Fix: Use minimal base images (alpine/distroless). Run containers as non-root user. Scan images with tools like Trivy/Snyk. Implement image signing. Use specific version tags, not 'latest'.
• Medium · Third-party Location Data Integration Security — app structure (integration points not shown). Application integrates with external location services (evident from README mentioning Google Timeline replacement). API key management and third-party data handling not visible. Fix: Store API keys in secure environment variables, never in code. Implement API rate limiting. Validate and sanitize all data from external sources. Use OAuth 2.0 for authentication flows. Implement data encryption for external API communications.
• Medium · Missing Input Validation Framework Evidence — app/models, app/controllers (not visible). No visible presence of Rails validation or input sanitization patterns in provided file structure. Risk of SQL injection or command injection. Fix: Use Rails built-in validators extensively. Implement strong parameters filtering. Use parameterized queries (Rails default). Validate all user inputs server-side. Implement rate limiting on API endpoints.
• Low · Public Repository Exposure of Configuration — .github/workflows/, .circleci/config.yml. Sensitive infrastructure configuration details may be exposed in public GitHub workflows (.github/workflows/), CI/CD configs (.circleci/config.yml), and docker-compose files. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.