207 lines
7.2 KiB
Markdown
207 lines
7.2 KiB
Markdown
## 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
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|