initial commit

README.md

@@ -0,0 +1,180 @@
+## 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 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)[DVM] in home
+    service k(logos:aws-ec2)[Kimai] in home
+    service db(database)[Database] in home
+
+    browser:R -- L:aw
+    dvm:T -- B:db
+    dvm:T -- B:k
+    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
+
+---
+
+## 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
+```
+
+---
+
+
+
+- **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).
+
+Your use-case provides an elegant balance between actionable productivity tracking and strong privacy guarantees offered by decentralized technologies.

slides.md

@@ -0,0 +1,81 @@
+---
+marp: true
+paginate: true
+backgroundColor: white
+auto-scaling: fittingHeader
+theme: default
+---
+
+<!--
+npx @marp-team/marp-cli pitch.md -o pitch.html --html=true
+
+-->
+
+# TrackStr
+
+## Proof of Work
+
+> “We're working on a new time-tracking system that’s fully peer-to-peer, with no trusted third party.”
+
+![bg right:50% height:600](./ostrich.png)
+
+---
+
+# Existing Native Apps
+
+* Hubstaff, Trackabi, Ever Gauzy
+* Screenshots, URL capture, mouse / keyboard tracking
+* Invasive, must trust a third party
+
+_High Proof, Low Sovereignty_
+
+---
+
+# Existing Web Apps
+
+* Toggl, Time Tagger, Kimai
+* Start / Stop Timer based
+* Easy to "game", or to forget the timer is running
+
+_Low Proof, High Sovereignty_
+
+---
+
+# Enter - Trackstr
+
+---
+
+# User Experience
+
+ - Start timer
+ - Periodically (configurable):
+   - Proof of Work (markdown notes, screenshots)
+   - Proof of Who (signed note)
+   - Proof of When (OTS)
+- Stop timer (is stopped automatically after certain period)
+
+---
+
+# Data Flow
+
+- Data encrypted and loaded to blossom
+- Link + decryption key sent to backend using DVM
+- backend downloads, decrypts, and stores in local DB
+
+---
+
+# Architecture
+
+- Web app 
+- Blossom
+- Relay
+- DVM
+- [Kimai](https://kimai.nostrdev.com/api/doc)
+
+![bg right:65% height:710](./architecture.png)
+
+---
+
+# Flow
+
+![bg right:75% height:600](./diagram1.png)