# guardianproject/haven architecture

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

- Interactive diagram: https://gitdiagram.com/guardianproject/haven
- Repository: https://github.com/guardianproject/haven

## Overview

##### Project type and purpose
- This is a native Android application (“Haven”) for physical‐space intrusion detection.
- It turns a phone into a multi-sensor monitoring device (motion, sound, light, power) that logs events locally and dispatches alerts via SMS, Signal, or a Tor‐exposed web server.

##### File structure
- Top-level build: Gradle (build.gradle, settings.gradle, gradle/).
- App code under src/main/java/org/havenapp/main:
- sensors/ (modules for accelerometer, microphone, camera, light, power)
- database/ + dao/ + model/ (Room database, converters, DAOs, asynchronous tasks)
- service/ (MonitorService, background jobs, SignalExecutorTask, WebServer)
- ui/ + resources/ (Activities, Fragments, adapters, layouts, drawables)
- resources/ (IResourceManager + ResourceManager)
- utils, preference manager, application initializer (HavenApp.java)
- Integration/config: AndroidManifest.xml, fastlane/ (CI & deployment), schemas/ (Room DB schemas), docs/, art/, tools/.

##### Key insights from README
- Sensors trigger events stored locally on a Room DB.
- A long‐running background service monitors sensors continuously.
- Notifications: SMS via platform API, Signal via libsignal‐service‐java.
- Remote access: bundled NanoHTTPd WebServer exposed as Tor Onion Service (Orbot).
- UI: configuration screens, event log, live preview, share overlay.

##### Main components
a. Sensor Subsystem
- Individual sensor classes (AccelerometerMonitor, AmbientLightMonitor, etc.)
- Media modules for camera/mic (AudioRecorderTask, VideoEncoder, ImageCodec)
b. Core Monitoring & Service Layer
- MonitorService (Android Service)
- HavenJobCreator + JobScheduler for periodic tasks (RemoveDeletedFilesJob)
- SignalExecutorTask for encrypted notifications
- WebServer (NanoHTTPd) for HTTP interface
c. Data Layer
- Room Database (HavenEventDB) + DAOs (EventDAO, EventTriggerDAO)
- Async tasks for CRUD operations
d. Notification & External Integrations
- SMS Manager (Android API)
- Signal‐service Java library
- Orbot/Tor for Onion Service
e. UI Layer
- Activities/Fragments (ListActivity, MonitorActivity, SettingsActivity, various ConfigureActivities)
- Adapters/ViewHolders for event list & media
- Custom AppIntro (PPAppIntro)
f. Configuration & Utilities
- PreferenceManager, Utils, ResourceManager
- Application subclass (HavenApp) for startup wiring

##### Relationships and interactions
- Sensors feed raw data → MonitorService.
- MonitorService applies threshold logic → when triggered:
- Insert event record into Room DB via DAO (async).
- Dispatch notifications:
– SMS via Android Telephony API
– Signal via libsignal integration (SignalExecutorTask)
- Write media files to local storage.
– WebServer hot-links logs & media files for remote access.
- UI layer reads from Room DB (via DAOs) to show event history and live preview.
- Settings UI writes to SharedPreferences via PreferenceManager.
- Tor/Orbot sits alongside WebServer, forwarding HTTP requests to the app’s local port.

##### Architectural patterns & principles
- Layered architecture (UI → Service → Data)
- Separation of concerns (sensors vs. storage vs. notification vs. UI)
- Use of Android components: Services for background work, JobScheduler for tasks, Activities for UI
- Asynchronous operations for I/O (AsyncTasks, Kotlin coroutines where used)
- Dependency inversion via ResourceManager and interfaces (IResourceManager)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        UI[/"Activities & Fragments"/]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        MS["MonitorService"]:::platform
        JC["HavenJobCreator\nRemoveDeletedFilesJob"]:::platform
        SET["SignalExecutorTask"]:::platform
        SS["SignalSender"]:::platform
        WS["WebServer"]:::platform
        BC["BackgroundCamera"]:::platform
    end

    %% Sensor & Media Layer
    subgraph "Sensor & Media Subsystem"
        direction TB
        SENSORS["AccelerometerMonitor\nAmbientLightMonitor\nBarometerMonitor\nBumpMonitor\nMicrophoneMonitor\nPowerConnectionReceiver"]:::app
        MEDIA["AudioRecorderTask\nVideoEncoder\nImageCodec\nAudioCodec\nMediaRecorderTask\nMicSamplerTask\nMicrophoneTaskFactory"]:::app
        MOTION["IMotionDetector\nLuminanceMotionDetector\nMotionDetector"]:::app
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB[(HavenEventDB)]:::db
        DAOS["EventDAO\nEventTriggerDAO"]:::app
        ASYNC["EventInsertAsync\nEventDeleteAsync\nEventInsertAllAsync\nEventDeleteAllAsync\nEventTriggerInsertAsync\nEventTriggerDeleteAsync"]:::app
        MIG["RoomMigration"]:::app
    end

    %% Notification Layer
    subgraph "Notification & External Integrations"
        direction TB
        SMS["Android Telephony API"]:::external
        SIGNAL["Signal Network"]:::external
    end

    %% Remote Access Layer
    subgraph "Remote Access"
        direction TB
        TOR["Tor Network (Orbot)"]:::external
        CLIENT["Remote Client"]:::external
    end

    %% Storage
    STORAGE[/"Media & Logs Storage"/]:::storage

    %% Interactions
    SENSORS -->|"raw data"| MS
    MEDIA -->|"media data"| MS
    MS -->|"insert event"| DB
    MS -->|"write media"| STORAGE
    MS -->|"dispatch SMS"| SMS
    MS -->|"dispatch Signal"| SIGNAL
    MS -->|"serve HTTP"| WS
    DB -->|"read events"| UI
    UI -->|"update prefs"| PM[PreferenceManager]:::app
    UI -->|"read/write settings"| PM
    WS --> TOR
    TOR --> CLIENT

    %% Configuration & Utilities
    HA[HavenApp]:::app
    PM[PreferenceManager]:::app
    UT[Utils]:::app
    RM[IResourceManager\nResourceManager]:::app

    HA --> MS
    HA --> DB
    HA --> RM
    UI --> UT

    %% Click Events
    click SENSORS "https://github.com/guardianproject/haven/tree/master/src/main/java/org/havenapp/main/sensors/"
    click AccelerometerMonitor "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/sensors/AccelerometerMonitor.java"
    click AmbientLightMonitor "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/sensors/AmbientLightMonitor.java"
    click BarometerMonitor "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/sensors/BarometerMonitor.java"
    click BumpMonitor "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/sensors/BumpMonitor.java"
    click MicrophoneMonitor "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/sensors/MicrophoneMonitor.java"
    click PowerConnectionReceiver "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/sensors/PowerConnectionReceiver.java"
    click MEDIA "https://github.com/guardianproject/haven/tree/master/src/main/java/org/havenapp/main/sensors/media/"
    click MOTION "https://github.com/guardianproject/haven/tree/master/src/main/java/org/havenapp/main/sensors/motion/"
    click MS "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/service/MonitorService.java"
    click JC "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/service/HavenJobCreator.kt"
    click JC "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/service/RemoveDeletedFilesJob.kt"
    click SET "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/service/SignalExecutorTask.kt"
    click SS "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/service/SignalSender.java"
    click WS "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/service/WebServer.java"
    click BC "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/service/BackgroundCamera.java"
    click DB "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/database/HavenEventDB.kt"
    click ASYNC "https://github.com/guardianproject/haven/tree/master/src/main/java/org/havenapp/main/database/async/"
    click DAOS "https://github.com/guardianproject/haven/tree/master/src/main/java/org/havenapp/main/dao/"
    click MIG "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/database/migration/RoomMigration.kt"
    click HA "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/HavenApp.java"
    click PM "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/PreferenceManager.java"
    click UT "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/Utils.java"
    click RM "https://github.com/guardianproject/haven/blob/master/src/main/java/org/havenapp/main/resources/ResourceManager.kt"

    %% Styles
    classDef ui fill:#D8BFD8,stroke:#800080,color:#000
    classDef platform fill:#ADD8E6,stroke:#0000FF,color:#000
    classDef app fill:#98FB98,stroke:#008000,color:#000
    classDef db fill:#FFFACD,stroke:#DAA520,color:#000
    classDef external fill:#FFA500,stroke:#FF8C00,color:#000
    classDef storage fill:#E6E6FA,stroke:#9370DB,color:#000
```
