## Product Overview
The solution "pow.do" is a privacy-focused, decentralized proof-of-work time tracking system built around Electron (client side), Blossom storage, Nostr protocol (events & relays), and a local Kimai instance for persisting time-tracking data.

## High-level Architecture

The overall solution is made up of:

 - **Local Client** (actual time tracker, an electron desktop app)
    - captures ActivityWatch data & screenshots
    - creates encrypted ZIP file and uploads to Blossom
    - creates signed Nostr Event linking to the ZIP file on Blossom
    - gift-wraps this event (NIP-17) and publishes it to a Nostr relay
 - **Public Server** (with Blossom file storage and Nostr event relay)
    - Blossom files regularly discarded
    - Relay whitelisted to end user npubs
 - **Private Server** (with Data Vending Machine, Kimai time tracking instance and a DB)
    - DVM monitors relay, picks up Nostr Event
    - DVM fetches ZIP file from Blossom
    - DVM sends collected Activity Watch data into a local DB
    - DVM updates Kimai instance with time tracking data

## Architecture Diagram

The architecture looks like this:

```mermaid
architecture-beta
    group user(internet)[End User PC]
    group dvms(internet)[21120 Server]
    group home(logos:aws-s3)[Private Server]
    group cloud(cloud)[Public Servers]

    service browser(internet)[Electron App] in user
    service aw(disk)[Activity Watch] in user

    service dvm(logos:aws-ec2)[Node JS] in dvms
    service pow[PoW API] in home
    service k(logos:aws-ec2)[Kimai] in home
    service db(database)[Database] in home

    browser:R -- L:aw
    dvm:T -- B:pow
    pow:T -- B:k
    pow:T -- B:db
    dvm:T -- B:relay
    dvm:T -- B:blossom

    
    service relay(disk)[Strfry Relay] in cloud
    service blossom(logos:aws-glacier)[Blossom File Storage] in cloud

    browser:L -- R:relay
    browser:L -- R:blossom


```


## Component Design

### **1. Electron App (Client side)**


- **Framework:** ElectronJS, Chromium frontend.
- **Responsibilities**:
  - Periodically capture user screenshots.
  - Query the local ActivityWatch API to collect usage data on a regular interval.
  - Bundle screenshots & ActivityWatch data as encrypted zip files and upload to Blossom server.
  - Use Blossom API to persist data securely.
  - Create signed Nostr Events referencing the stored Blossom files.
  - Gift-wrap (encrypt/secure via NIP-17) the Nostr event for enhanced privacy/security.
  - Publish the gift-wrapped event to a Nostr relay.
- **Required Libraries/Tools**:
  - Electron framework (UI & client app)
  - Node.js scripting
  - ActivityWatch API Client (REST API calls)
  - Blossom API Client (REST API - file upload handling)
  - Nostr protocol JS client (e.g., nostr-tools library)
  - ZIP/compression libraries (`adm-zip`, `archiver`)
  - `nostr-tools` (JavaScript) or equivalent
  - encryption/decryption utility supporting NIP-17

---

### **2. Blossom File Storage Service**
- **Description:** Decentralized hash-based file storage to securely store ZIP archives of screenshots & ActivityWatch data.
- **Data Flow:** Electron app → encrypted zip → Blossom Server (via REST API)
- **Security & Privacy:** Files are hash-identified, no direct user-identification metadata exposed.  Content is encrypted.
---

### **3. Nostr Relay**
- **Description:** Decentralized event publishing via signed JSON messages (Nostr event).
- **Nostr Usage**:
  - **Publishing**: Electron client creates Nostr events, signs them, and publishes to relay servers.
  - **Gift-wrapping (NIP-17)**: Electron client encrypts events using NIP-17 before publishing, ensuring that only the DVM can decrypt and access the Blossom file URLs.


---

### **4. Data Vending Machine (DVM)**
- **Description:** The DVM is a separate backend (or daemon) that:
  - Subscribes to the chosen Nostr relay.
  - Receives and decrypts the gift-wrapped Nostr events (using NIP-17 technique).
  - Fetches the referenced ZIP file from Blossom (via Blossom API).
  - Unzips & extracts data (screenshots/activity logs).
  - Parses extracted activitywatch / screenshot data and sends it to the DB
  - Tracks ongoing time usage and updates the dedicated Kimai API endpoints.

- **Client-to-DVM Data Flow**:
  ```plaintext
  Electron Client 
    → Nostr event signed & gift-wrapped event with Blossom file URL
    → Sent to relay
    → DVM subscribes to Nostr relay feed, receives gift-wrapped event
  ```
- **Data Flow in DVM**:
  ```plaintext
  Nostr Relay → DVM (relay subscription)
    → Event Decryption (NIP-17)
    → Blossom download (via hash)
    → Data Parsing (python/node — depending on language preference)
    → Kimai API call (add/update time-entry, activity, and time data)
  ```

- **Libraries & dependencies**:
  -Python or Node.js client for Nostr events (`nostr-tools` in Node)
  - HTTP client for Blossom API (authenticated/file download)
  - HTTP client for Kimai API updates/addition of entries (`requests` or `axios`)
  - ZIP utilities for unzipping (e.g., Node.js's `adm-zip` or `unzip`)

---

### **5. Kimai (Local Instance)**
- **Description:** Open-source time tracking tool storing final extracted data.
- **Deployed Local/Privately**: As per your requirements—keeping all time-tracked data internal/private.
- **Data Flow**:
  ```plaintext
  DVM → Kimai API (insert/update entries)
  ```
- **Setup Considerations**:
  - Host Kimai locally in a container with no public IP access.
  - DVM accesses Kimai API endpoints directly.

---

## Security & Privacy Considerations

- **Event Encrypting & Security**: Utilizing NIP-17 ensures additional confidentiality.
- **File hashing/storage (Blossom):** Secure with cryptographic hashing, eliminating data manipulation risks.
- **Privacy**: Nostr Relay protects both Server and Client IPs
- **Decentralization**: Leveraging open protocols (Nostr), distributed storage systems (Blossom).
- **Traceability**: The data trail remains verifiable and secured (signed events, cryptographic proof via Blossom hashes, encrypted via NIP-17).
- **Flexibility**: Easy to scale or swap out components later if required (Blossom → alternative storage, Kimai → other time-tracking tools).

---

## High-level Sequence Diagram (text-based)

```plaintext
Electron App:
  ├─ Capture Screenshots & ActivityWatch data
  └─ Upload ecnrypted ZIP to Blossom server (API)

Electron App:
  ├─ Create JSON Nostr Event (signed via keypair)
  ├─ Gift-wrap (NIP-17 encryption)
  └─ Publish event to Nostr relay

DVM (Backend):
  ├─ Listen to Relay for events
  ├─ Decrypt Nostr Event via NIP-17 (Gift-wrap)
  ├─ Use content from event to download ZIP from Blossom
  ├─ Extract ZIP and parse data
  └─ Upload parsed data to DB
  └─ Add time entries to Kimai via REST/API
```


Mermaid flow:

```mermaid
sequenceDiagram
    autoNumber

    actor u as User
    participant e as Electron App
    participant b as Blossom
    participant r as relay
    participant d as dvm

    u->>e: Choose project <br> & Start timer
    Note over u: Do work & <br> prepare PoW
    u->>e: Register PoW
    e->>b: Load encrypted<br> PoW to Blossom
    e->>r: Notify DVM
    Note over u: Snooze
    d<<->>r: Fetch notification
    Note over d: fetch & decrypt<br> data, add <br> to DB
    Note over d: stop timer after<br> interval
    
```