# freika/dawarich architecture

> Architecture diagram of the GitHub repository freika/dawarich, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freika/dawarich
- Repository: https://github.com/freika/dawarich

## Overview

##### Main Components Overview
The system should be divided into these major components:

a) Frontend Layer:
- Web Interface (Rails Views + JavaScript)
- Real-time Components (ActionCable)
- Visualization (JavaScript/Maps)

b) Backend Layer:
- API Controllers (REST + WebSocket)
- Business Logic Services
- Background Jobs (Sidekiq)
- Authentication (Devise)

c) Data Layer:
- PostgreSQL Database
- Redis (for caching and Sidekiq)
- File Storage (Active Storage)

##### Key Architectural Elements

a) Core Services:
**Import Services**
- Google Maps Import
- OwnTracks Import
- GPX/GeoJSON Import
- Photo Geodata Import (Immich/Photoprism)

**Location Processing**
- Reverse Geocoding
- Visit Detection
- Area Detection

**Export Services**
- GeoJSON Export
- GPX Export

b) Real-time Features:
- WebSocket Channels for live updates
- Background job processing for heavy tasks

##### Integration Points
- External APIs (Reverse Geocoding)
- Photo Management Systems (Immich/Photoprism)
- Location Tracking Apps (Overland, OwnTracks, etc.)

- Rectangles: Main components
- Hexagons: External services
- Rounded rectangles: Internal services

- Blue: Frontend components
- Green: Backend services
- Yellow: Data stores
- Gray: External services

**→ REST API calls**
**⇢ WebSocket connections**
**⇄ Bi-directional data flow**

##### Key Workflows to Highlight

a) Location Data Flow:
**Mobile App → API → Background Jobs → Database → Map Visualization**

b) Import Process:
**Import File → Import Service → Background Processing → Database → Statistics Calculation**

c) Real-time Updates:
**Location Update → WebSocket → Frontend Map → User Interface**

##### Deployment Architecture
**Docker Container Structure:**
- Web Application (Rails)
- Sidekiq Worker
- PostgreSQL
- Redis

Remember to emphasize:
- The modular nature of the import/export system
- Real-time capabilities
- Background processing architecture
- Data flow between components
- Security boundaries
- Integration points with external services

This will provide a clear understanding of how Dawarich processes, stores, and visualizes location data while handling various import sources and real-time updates.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        WI["Web Interface"]:::frontend
        MC["Map Components"]:::frontend
        RT["Real-time Components"]:::frontend
    end

    subgraph API
        REST["REST API Controllers"]:::api
        WS["WebSocket Controllers"]:::api
    end

    subgraph Services
        subgraph ImportServices
            GMI["Google Maps Import"]:::service
            OTI["OwnTracks Import"]:::service
            GPI["GPX/GeoJSON Import"]:::service
            PHI["Photo Geodata Import"]:::service
        end

        subgraph LocationProcessing
            RG["Reverse Geocoding"]:::service
            VD["Visit Detection"]:::service
            AD["Area Detection"]:::service
        end

        subgraph ExportServices
            GJE["GeoJSON Export"]:::service
            GPXE["GPX Export"]:::service
        end
    end

    subgraph BackgroundProcessing
        SQ["Sidekiq Queue"]:::queue
        BJ["Background Jobs"]:::service
    end

    subgraph DataStorage
        PG[(PostgreSQL)]:::database
        RD[(Redis)]:::database
        FS["File Storage"]:::storage
    end

    subgraph ExternalServices
        GEO["Geocoding API"]:::external
        IMS["Immich Service"]:::external
        PPS["Photoprism Service"]:::external
        OTS["OwnTracks Service"]:::external
    end

    %% Frontend Connections
    WI --> REST
    WI --> WS
    RT --> WS
    MC --> REST

    %% API Layer Connections
    REST --> ImportServices
    REST --> LocationProcessing
    REST --> ExportServices
    WS --> BJ

    %% Service Connections
    ImportServices --> BJ
    LocationProcessing --> BJ
    BJ --> PG
    BJ --> RD
    
    %% External Service Connections
    LocationProcessing --> GEO
    PHI --> IMS
    PHI --> PPS
    OTI --> OTS

    %% Data Storage Connections
    PG --> REST
    RD --> WS
    FS --> REST

    %% Click Events
    click WI "https://github.com/Freika/dawarich/tree/master/app/views/"
    click MC "https://github.com/Freika/dawarich/tree/master/app/javascript/maps/"
    click RT "https://github.com/Freika/dawarich/tree/master/app/javascript/channels/"
    click REST "https://github.com/Freika/dawarich/tree/master/app/controllers/api/v1/"
    click WS "https://github.com/Freika/dawarich/tree/master/app/channels/"
    click GMI "https://github.com/Freika/dawarich/tree/master/app/services/google_maps/"
    click OTI "https://github.com/Freika/dawarich/tree/master/app/services/own_tracks/"
    click RG "https://github.com/Freika/dawarich/tree/master/app/services/reverse_geocoding/"
    click BJ "https://github.com/Freika/dawarich/tree/master/app/jobs/"
    click IMS "https://github.com/Freika/dawarich/tree/master/app/services/immich/"
    click PPS "https://github.com/Freika/dawarich/tree/master/app/services/photoprism/"

    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef service fill:#e74c3c,stroke:#c0392b,color:white
    classDef queue fill:#f1c40f,stroke:#f39c12,color:white
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef storage fill:#1abc9c,stroke:#16a085,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
```
