documentations update

.gitignore

···
 
 node_modules
 docs/*
-!docs/readme
+!docs/readme-*
 dist
 *.local
 .eslintcache

readme.org

···
 #+AUTHOR: Jonathan Raphaelson
 #+EMAIL: [e-mail]
 
-An offline first RSS & Podcast PWA Application
+an offline-first RSS & podcast PWA application
 
-* What is Skypod?
+* what is skypod?
 
 - rss/podcast subscription management
 - offline first; cache audio locally, and p2p sync between devices
-- podcast playback with nice features; skip silence, volume correction, etc.
+- podcast playback with nice features; skip silence, volume
+  correction, etc.
 - fun to hack on
 
-* How does it work?
+* how does it work?
 
-- PWA stores and displays cached feeds, subscription, and listening history data locally
-- Feed proxy server provides a nice API for fetching feeds and extracting metadata
-- WebSocket signaling server for WebRTC peering, devices sync cached data and play state
+- PWA stores and displays cached feeds, subscription, and listening
+  history data locally in IndexedDB
+- WebSocket signaling server for WebRTC peering, devices sync cached
+  data and play state using a hybrid logical clock for causal ordering
+- feed proxy server provides a nice API for fetching feeds and
+  extracting metadata
 
-* Development
+* getting started with devenv
 
-Run the pwa+server with:
+this project uses [[https://devenv.sh][devenv.sh]] for reproducible development environments.
+
+if you have devenv installed:
+
+#+BEGIN_SRC bash
+  $ devenv shell
+  $ npm install
+  $ npm run dev
+#+END_SRC
+
+if you don't have devenv, you can install it from [[https://devenv.sh][devenv.sh]] or just
+use node v24+ directly.
+
+* development
+
+run the pwa+server with:
 
 #+BEGIN_SRC bash
   $ npm install
   $ npm run dev # lots of stuff concurrently with wireit
 #+END_SRC
 
-- Common
-  - ES2024 Javascript, running on in modern browsers or [[https://nodejs.org][Node v24]]
-  - [[https://github.com/panva/jose][~jose~]] for cross-platform webcrypto and JWT management
-  - [[https://zod.dev/][Zod v4]] describes schema and builds transformation pipelines
-- Backend
-  - [[https://expressjs.com/][Express]] and Node's ~stdlib~ for HTTP and WebSocket servers
-- Frontend
-  - [[https://vite.dev/][Vite]] does FE builds
-  - [[https://preactjs.com/][Preact]] + [[https://zustand.docs.pmnd.rs][Zustand]] for UI
-- Build & DX
-  - [[https://github.com/google/wireit][Wireit]] does script dependencies and services
-  - [[https://jsdoc.app/][JSDoc]], along with [[https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html][Typescript's JSDoc support]] does typechecking
-  - [[https://eslint.org][ESLint]] and a plethora of plugins keeps the code nice
+this starts:
+- vite dev server at ~http://127.0.0.1:4000~ (frontend)
+- backend server at ~http://127.0.0.1:4001~ (WebSocket + API)
+- live type-checking and linting in watch mode
+
+** technology stack
 
-Still thinking about:
+*** common
+- typescript with strict mode
+- [[https://github.com/panva/jose][~jose~]] for cross-platform webcrypto and JWT management
+- [[https://zod.dev/][Zod]] describes schema and builds transformation pipelines
 
-- [[https://dexie.org/][Dexie]] for browser storage and enabling syncing
-- per-realm SQLite databases with node's native sqlite support
-- docker compose for deployment with self-hosted realm storage
+*** backend
+- [[https://expressjs.com/][Express]] for HTTP and WebSocket servers
+- [[https://github.com/Level/level][Level]] for persistent realm kv storage
 
-See [[./readme-devlog.org]] for design and architecture thoughts.
+*** frontend
+- [[https://vite.dev/][Vite]] for builds
+- [[https://preactjs.com/][Preact]] for UI
+- [[https://dexie.org/][Dexie]] for IndexedDB storage
+- [[https://github.com/feross/simple-peer][simple-peer]] for WebRTC
 
-** Scripts
+*** build & dx
+- typescript for type-checking
+- [[https://github.com/google/wireit][Wireit]] does script dependencies and services
+- [[https://eslint.org][ESLint]] and prettier keep the code nice
 
-All scripts can have ~--watch~ passed as an argument to have ~wireit~ rerun when inputs change.
-This is not useful for everything.
+** scripts
 
 - ~npm run dev~ :: alias for ~npm run start:dev~
 - ~npm run lint~ :: runs ~eslint~
 - ~npm run types~ :: runs ~tsc~ (no emitting, just typechecking)
-- ~npm run docs~ :: runs ~jsdoc~ to generate docs in ~./docs~
+- ~npm run build~ :: build production frontend
 - ~npm run test~ :: runs ~jest~ as a one-off
-- ~npm run start:dev~ :: runs BE/FE, tests in watch mode, and typecheck/linting
+- ~npm run start:tests~ :: runs ~jest~ in watch mode
+- ~npm run start:dev~ :: runs BE/FE with live type-checking and linting
 - ~npm run start:prod~ :: builds and runs everything in production mode
 
-* Contributing
+** running tests
+
+There's not much here yet, I want to figure it out first.
+
+#+BEGIN_SRC bash
+  $ npm run test              # run all tests once
+  $ npm run start:tests       # run tests in watch mode
+#+END_SRC
+
+to run a single test file:
+
+#+BEGIN_SRC bash
+  $ npx jest src/path/to/file.spec.ts
+#+END_SRC
+
+** git hooks
+
+pre-commit hook runs type-checking and linting automatically. enable with:
+
+#+BEGIN_SRC bash
+  $ git config core.hooksPath .githooks
+#+END_SRC
+
+* architecture
+
+the codebase is organized into modules with path aliases:
+
+- ~#client/*~ (~src/client/~) - preact frontend application
+- ~#server/*~ (~src/server/~) - node.js express backend
+- ~#common/*~ (~src/common/~) - shared code (protocol, crypto, utilities)
+- ~#realm/*~ (~src/realm/~)   - p2p connection and sync protocol
+- ~#skypod/*~ (~src/skypod/~) - domain-specific schemas and actions
+
+** key architectural components
+
+*** p2p synchronization
+
+uses a hybrid logical clock (HLC) for causal ordering of events across
+distributed peers. clients PULL complete action history when catching
+up, and PUSH tailored updates to each peer based on knowledge vectors.
+
+*** offline-first
+
+all user data lives in IndexedDB via dexie. the server is stateless
+regarding user data (only maintains ephemeral realm/peer state).
+
+*** webrtc for p2p
+
+peers communicate directly via WebRTC data channels. the WebSocket
+connection to the server is only used for signaling and as a fallback
+broadcast mechanism.
+
+*** realm system
+
+a realm is a collection of verified identities that can communicate
+securely. realms are not publicly routable; access requires the realm
+id and an invitation from an existing member.
+
+see [[./docs/readme-brainstorm.org]] for detailed architecture thoughts
+and connection flow diagrams.
 
-- run ~git config core.hooksPath .githooks~ to install pre-commit hooks for lint/fmt
-- not really open to contributions right now, come back later.
+* contributing
 
-* License & Copyright
+- run ~git config core.hooksPath .githooks~ to install pre-commit
+  hooks for lint/fmt
+- honestly, not really open to contributions right now, come back
+  later.
 
-Copyright (C) 2025 Jonathan Raphaelson
+* license & copyright
 
-This program is free software: you can redistribute it and/or modify it under the terms of
-the **Affero General Public License verson 3 or later** (AGPLv3+).
+copyright (C) 2025 jonathan raphaelson
 
-Please see [[./readme-license.txt]] for a copy of the full license.
+this program is free software: you can redistribute it and/or modify
+it under the terms of the **affero general public license version 3 or
+later** (AGPLv3+).
+
+see [[./readme-license.txt]] for a copy of the full license.