From 7381c5bcb5bdaadde37fc3f435f7a4e901b233a9 Mon Sep 17 00:00:00 2001 From: Kevin Nzeng Essimengane Date: Sat, 18 Jul 2026 02:15:03 +0200 Subject: [PATCH] docs: add Dotify book charter --- docs/README.md | 11 ++ docs/book/README.md | 289 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.html | 30 ++++- 3 files changed, 326 insertions(+), 4 deletions(-) create mode 100644 docs/book/README.md diff --git a/docs/README.md b/docs/README.md index 52dea84..f366029 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,16 @@ Conceptual documents that help you understand why Dotify works the way it does. --- +## Book + +A long-form companion text for learning from Dotify as it is built. + +| Document | Audience | Summary | +|---|---|---| +| [Dotify Book Charter](./book/README.md) | Developers, builders, artists | Working table of contents and evidence standard for the companion book | + +--- + ## Reference Precise technical descriptions for developers integrating with or contributing to Dotify. @@ -39,3 +49,4 @@ Precise technical descriptions for developers integrating with or contributing t - [contracts/README.md](../contracts/README.md) — contract architecture and deployment - [web/README.md](../web/README.md) — frontend local setup and build commands - [CLAUDE.md](../../CLAUDE.md) — repository commands and development guidance +- [Book charter](./book/README.md) — how the companion book will connect product, code, and culture diff --git a/docs/book/README.md b/docs/book/README.md new file mode 100644 index 0000000..caeebba --- /dev/null +++ b/docs/book/README.md @@ -0,0 +1,289 @@ +# Let the Music Connect the Dots + +Status: book charter and working table of contents. + +This book is the companion text for Dotify. It should teach a reader how to +build a full-stack decentralized application while also making the cultural, +social, and philosophical argument visible. + +Dotify itself remains the primary artifact. The book explains what the artifact +is proving, how each technical decision works, what Web3 adds, what it costs, +and which claims are still unproven. + +## Working title + +**Let the Music Connect the Dots: Building a Sovereign Cultural Commons with +Polkadot** + +## Promise + +The book should help a reader understand Dotify at three levels: + +1. Product: why shared listening, artist sovereignty, protected access, and + human-centered discovery belong in the same application. +2. Engineering: how to build the app from frontend, rooms, WebRTC, backend key + delivery, encrypted media, IPFS, and artist-owned runtimes. +3. Culture: why blockchain is useful only when it solves a real social problem + without turning the human experience into bureaucracy. + +The book must not be a detached manifesto. Every technical claim should point to +code, tests, PRs, issues, operational evidence, or a clearly marked open +question. + +## Audience + +- Full-stack developers who want to learn how to build a real Web3 application. +- Product builders who want to understand where blockchain helps, where it does + not, and how to avoid wallet-first product design. +- Web3 readers who want a concrete example of applied sovereignty, trust, and + cultural transmission. +- Artists, curators, and community builders who want to understand how digital + infrastructure can protect creative agency. + +## Evidence Standard + +Every chapter and major section should carry one of these labels: + +| Label | Meaning | +| --- | --- | +| `Implemented` | The behavior exists in the repository and has code references. | +| `Validated` | The behavior exists and has automated tests, CI, deployment evidence, or manual production evidence. | +| `Experimental` | The idea has a prototype or spike, but the production boundary is not final. | +| `Aspirational` | The concept belongs to the Dotify thesis but is not implemented yet. | +| `Rejected` | The project considered the path and chose not to take it, with reasons. | + +This protects the book from becoming marketing. It also lets readers learn from +the unfinished parts without confusing them with shipped guarantees. + +## Voice + +Use plain technical language when precision matters. Use cultural and +philosophical language only when it clarifies the product decision. + +Good book prose should answer: + +- What human problem is this section about? +- What is the Web2 baseline? +- What does Web3 add here? +- What new risks or costs does Web3 introduce? +- How does Dotify implement the idea today? +- What remains unresolved? + +Avoid decorative philosophy. The philosophy should appear inside the product +mechanics: room entry, access gates, artist runtime ownership, key custody, +royalty visibility, personhood caution, and social propagation rules. + +## Scope + +Included: + +- The Dotify product thesis. +- Full-stack app construction from local development to public testnet + operation. +- React/Vite frontend structure. +- Socket.IO signaling and WebRTC room playback. +- Backend-mediated uploads and content-key delivery. +- Encrypted audio access with honest limits. +- IPFS and gateway reliability. +- Artist-owned SmartRuntime contracts. +- Royalties, access policy, and runtime transparency. +- Product SDK, Playground, Statement Store, and Humanity as gated feasibility + tracks. +- Security, threat modeling, test strategy, and operational runbooks. +- Cultural propagation and ambassador mechanics only after consent and + anti-abuse foundations are designed. + +Excluded until proven: + +- Tokenomics as a primary product story. +- Claims of full DRM. +- Claims that Proof of Personhood is live. +- Claims that Product SDK Host mode is production-ready for Dotify. +- Claims that room guests receive protected source access. +- Referral mechanics without provenance, consent, and anti-abuse design. + +## Annotated Table of Contents + +### Part I - Why Music Needs a Commons + +Purpose: explain the social problem before introducing technical machinery. + +1. **The private headphone city** (`Aspirational`) + - Shared spaces contain isolated listeners. + - Music is not only content; it is memory, invitation, and relation. + - Dotify asks whether a shared track can reopen a temporary commons. + +2. **Not Spotify with a wallet** (`Implemented`) + - Explain why individual consumption is not Dotify's center. + - Introduce the product triangle: shared presence, artist sovereignty, and + invisible trust. + - Reference: `docs/context/dotify-product-memory.md`. + +3. **The Web2 baseline** (`Aspirational`) + - Compare a normal streaming platform, a chat room, and a payment platform. + - Name what those systems do well. + - Name the capture problem: platform-owned catalog rules, opaque value + flows, fragile access boundaries, and algorithmic discovery without + social relation. + +### Part II - First Sound + +Purpose: teach the reader to build the first useful listening product before +adding heavier Web3 machinery. + +4. **The listener surface** (`Implemented`) + - Build the Music view: catalog, track cards, access badges, player, and + room controls. + - Explain why the first screen is the app, not a marketing page. + - Reference: `web/src/views/ListenView.tsx`. + +5. **Rooms as the social core** (`Implemented`) + - Build one-link rooms with hosted signaling and WebRTC. + - Explain why room guests do not need wallets. + - Reference: `docs/explanation/listening-rooms.md`. + +6. **The host-access doctrine** (`Validated`) + - Show the room security boundary: the host may receive a temporary key; the + guest receives only an ephemeral WebRTC stream. + - Reference: `docs/product/room-access-policy.md`. + +### Part III - Artist Sovereignty + +Purpose: show how blockchain enters because the artist needs control, not +because the product needs a crypto aesthetic. + +7. **The artist-owned runtime** (`Implemented`) + - Explain SmartRuntimes, factory deployment, and the artist directory. + - Show how one artist gets one runtime and why that matters politically and + technically. + - Reference: `docs/reference/contracts-api.md`. + +8. **Publishing a protected release** (`Validated`) + - Walk through upload, encryption, metadata, IPFS, and on-chain + registration. + - Contrast demo browser upload with backend-mediated production upload. + - Reference: `docs/reference/environment-variables.md`. + +9. **Royalties as inspectable value flow** (`Validated`) + - Explain Classic payment, royalty splits, collaborator shares, and runtime + reads. + - Reference: `docs/explanation/royalty-settlement.md`. + +### Part IV - Protected Access Without False Promises + +Purpose: teach security boundaries honestly. + +10. **What encrypted delivery protects** (`Validated`) + - Explain key custody, signed key requests, replay protection, and denied + playback. + - State the limit clearly: this is distribution access protection, not full + DRM. + - Reference: `docs/explanation/content-protection.md`. + +11. **Dotify Audio V2** (`Experimental`) + - Explain DAV2 chunked encrypted media, startup behavior, gateway reads, + fallback strategy, and why first sound matters. + - Reference: `docs/reference/audio-v2-container.md`. + +12. **Gateway reality** (`Experimental`) + - Explain IPFS gateway behavior, browser range reads, cache behavior, and + the backend read-through decision. + - Tie this to the active DAV2 validation gate. + - Reference: `docs/backlog/polkadot-product-readiness-and-killer-dapp-roadmap.md`. + +### Part V - Making Web3 Disappear + +Purpose: align Dotify with the current Polkadot product ecosystem without +pretending the future is already shipped. + +13. **Product SDK as progressive enhancement** (`Experimental`) + - Explain Host capabilities, Product accounts, resource allocation, and why + standalone web remains first-class. + - Reference: `docs/backlog/polkadot-product-readiness-and-killer-dapp-roadmap.md`. + +14. **Statement Store and presence** (`Experimental`) + - Explain why small signed ephemeral statements fit presence better than + media, chat history, SDP/ICE, or durable catalog metadata. + +15. **Human free and the dignity problem** (`Aspirational`) + - Explain why personhood is philosophically central and technically + dangerous. + - Require privacy, address binding, fallback UX, and non-surveillance + before implementation. + - Reference: `docs/backlog/11-proof-of-personhood-integration-research.md`. + +### Part VI - Operating a Cultural Commons + +Purpose: show that production readiness is part of the philosophy. + +16. **The production spine** (`Implemented`) + - Explain deployable frontend, backend, signaling, contracts, env guards, + health checks, and smoke tests. + - Separate delivered production guarantees from active DAV2/gateway + validation and backend read-through decisions. + - Reference: `docs/backlog/README.md`. + +17. **Tests as cultural honesty** (`Validated`) + - Explain why critical flows are tested: Classic unlock, artist publish, + room joining, access-state failures, and production env checks. + - Show how tests defend the product promise from accidental regressions. + +18. **PRs as teaching artifacts** (`Implemented`) + - Explain PR descriptions as knowledge transfer between coder and reviewer. + - Every PR should explain why it exists, what issue it solves, how the code + works, what reviewers should inspect, what evidence was collected, and + what remains open. + +### Part VII - The Unfinished Commons + +Purpose: keep the poetic ambition and engineering discipline together. + +19. **Consented cultural propagation** (`Aspirational`) + - Design provenance around consent, room context, and meaningful discovery, + not referral spam. + - Reference: `docs/backlog/12-ambassador-social-propagation-model.md`. + +20. **The ambassador is not a marketer** (`Aspirational`) + - Explain cultural transmission as care. + - Define anti-abuse principles before mechanics. + +21. **What remains unresolved** (`Aspirational`) + - Name the hard questions: capture, identity, privacy, gateway reliability, + governance, community memory, and the limits of software. + +## Chapter Template + +Each chapter should follow this rhythm: + +1. **Lived situation** - a human scenario before the technical abstraction. +2. **Claim** - the product or philosophical proposition. +3. **Architecture** - the system pieces involved. +4. **Lab** - a concrete implementation walkthrough. +5. **Security review** - what can fail, what is protected, and what is not. +6. **Evidence** - code references, tests, PRs, issues, screenshots, or manual + checks. +7. **Open question** - what the project still has to prove. + +## Repository Workflow + +The book should be maintained with the same discipline as code. + +1. When a PR introduces a new concept, include a reviewer-learning paragraph in + the PR description. +2. If the concept is durable, add or update the matching explanation, + reference, manual, or book note. +3. Mark the book section with the correct evidence label. +4. Link to the issue, PR, tests, docs, and operational proof. +5. Keep aspirational sections short until implementation begins. +6. Update `docs/index.html` when the book changes public framing or introduces a + major public-facing resource. + +## Initial Milestones + +1. Create this charter and expose it from the documentation index. +2. Draft Part I as explanation, not tutorial. +3. Draft the first tutorial chapter only after the corresponding app flow is + stable enough that readers can reproduce it. +4. Add a short "Book notes" section to future PR descriptions when the PR + teaches a concept that belongs in the book. +5. Keep the book honest: if Dotify has not proven something, the book says so. diff --git a/docs/index.html b/docs/index.html index 80e89c4..917a93e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -857,6 +857,12 @@ color: var(--slate-strong); } + .manifesto-actions { + display: flex; + flex-wrap: wrap; + gap: 0.75rem; + } + .resources { padding: clamp(4.5rem, 8vw, 6.5rem) 0; border-top: 1px solid var(--line); @@ -1555,10 +1561,16 @@

Product SDK, personhood, and cultural transmission

Dotify is not a Spotify clone. It is a cultural social hub where music can reopen a commons between people without dispossessing the artist.

- - Read the north star - - +
+ + Read the north star + + + + Open the book charter + + +
@@ -1607,6 +1619,15 @@

Explore the project

+
  • + + + Book charter + The companion book plan: technical lessons, cultural thesis, and evidence rules. + + + +
  • @@ -1630,6 +1651,7 @@

    Explore the project