Dawarich

Dawarich is a self‑hosted web application that reconstructs and visualizes personal location history, positioning itself as an open alternative to Google Timeline. From a developer’s standpoint, it is built around a modern full‑stack architecture that emphasizes modularity, data privacy, and ease of integration. The core goal is to ingest raw GPS streams (GPX, GeoJSON, OwnTracks JSON, etc.), persist them in a relational store, and expose rich visualizations through a responsive React frontend. The system is designed to run in Docker containers, making it trivial to deploy on any infrastructure that supports Compose or Kubernetes.

• Backend: A Node.js/TypeScript service built with the NestJS framework. It exposes a RESTful API that accepts location payloads from various client apps (OwnTracks, Home Assistant, GPSLogger). NestJS’s modular architecture allows developers to plug in additional providers or extend authentication logic without touching core code.
• Database: PostgreSQL is the primary persistence layer, leveraging PostGIS for geospatial indexing. This enables efficient spatial queries (e.g., nearest‑point, distance calculations) and supports the statistical dashboards that compute total miles, country visits, and travel routes.
• Frontend: A single‑page React application using TypeScript, styled with Tailwind CSS. Map rendering is handled by Leaflet (or optionally Mapbox GL) to provide an interactive, zoomable map with custom markers and heatmaps. The UI is built around reusable components that can be overridden or extended through a theming system.
• Containerization: All services (API, UI, PostgreSQL) are packaged in Docker images. The docker/docker-compose.yml file defines volumes for data persistence and secrets, while environment variables control feature flags (e.g., enable/disable trip creation).
• CI/CD: CircleCI pipelines automate linting, testing, and image publishing. The repo’s CHANGELOG.md and semantic versioning help developers track breaking changes.

• Location Ingestion: Endpoints /api/v1/locations accept JSON payloads from client apps. The API validates timestamps, coordinates, and optional metadata before persisting them.
• Trip Management: Developers can programmatically create, update, or delete trips via /api/v1/trips. The backend auto‑generates a trip route by clustering consecutive location points that fall within the specified date range.
• Statistical Endpoints: Aggregated metrics (total distance, number of cities visited, daily movement) are available under /api/v1/stats. These endpoints return GeoJSON for map overlays, making it easy to build custom dashboards.
• Webhooks & Events: The system can emit events on new location ingestion or trip completion. Clients can subscribe via HTTP callbacks, enabling real‑time integrations with external services (e.g., Home Assistant automations).
• Extensibility: The plugin architecture allows adding new data sources or export formats. For instance, a developer can write a plugin that pulls location data from a custom IoT device and forwards it to the Dawarich API.

• Self‑Hosting: Dawarich is intended for personal or small‑team use; it runs on any Linux host that supports Docker. The Compose file sets up three containers: api, frontend, and db. Data volumes are mounted to /var/lib/postgresql/data for persistence.
• Scalability: While the default single‑instance setup is sufficient for personal use, the architecture can be horizontally scaled by deploying multiple API replicas behind a load balancer. PostgreSQL can be moved to a managed cluster (e.g., RDS) for larger datasets.
• Security & Privacy: All network traffic is served over HTTPS (self‑signed or Let's Encrypt). The database can be encrypted with LUKS, and the API supports JWT authentication. These features make Dawarich suitable for privacy‑conscious developers who want to keep data on their own servers.

• Plugin System: Developers can create plugins that hook into the NestJS lifecycle. For example, a plugin could add support for ingesting data from a new GPS logger or enrich location points with reverse‑geocoded addresses.
• Custom Webhooks: The API’s webhook support allows external services to react instantly to new data. A developer could trigger a Slack notification whenever a user enters a new country.
• API Clients: The public API is documented in OpenAPI format. SDKs can be autogenerated for TypeScript, Python, or Go, simplifying integration into existing workflows.
• UI Customization: The React front‑end exposes a theming API and supports custom CSS overrides. Developers can build bespoke dashboards or embed the map component into other applications.

• Documentation: The repo includes comprehensive guides (docs/) covering setup, data ingestion, API usage, and contribution workflow. The CONTRIBUTING.md file outlines coding standards and pull request procedures.
• Community: An active Discord channel provides real‑time support. Issues and pull requests are triaged promptly, reflecting a healthy open‑source community.
• Configuration: Environment variables control every aspect of the stack—API port, database credentials, feature flags. This makes it easy to tailor the deployment to specific needs (e.g., disabling trip creation for a minimal install).