index

WhatNext Documentation Index

For LLMs: This index maps all documentation in the repository by concept. Use this for quick navigation and context gathering.

Core Documentation

Project Foundation

  • whtnxt-nextspec - Complete technical specification and architecture (source of truth)
  • the-walled-garden-cracks - Vision supplement: Spotify API crackdown, coordinator model, translation layer architecture (2026-02)
  • srs-whatnext - Software Requirements Specification (MVP baseline v0.1.0)
  • architecture-whatnext - Architecture Design Document (MVP baseline v0.1.0)
  • README - High-level overview and stack
  • CLAUDE - Development instructions, commands, architecture principles

Development Workflows

Concepts & Architecture

P2P Networking

Peer-to-Peer libp2p WebRTC

Data Architecture

Local-First Data RxDB

UI/UX

Electron React Tailwind

Development Milestones

Issue 10: libp2p Integration

V0.0.0 Release

Repository Structure

Application Components

/app                    Main Electron application
  /src/main            Main process (Node.js)
  /src/renderer        Renderer process (React)
  /src/main/preload.ts IPC bridge (security boundary)
  /docs                App-specific documentation

/test-peer             Barebones libp2p test peer for P2P development
  README.md            Test peer usage guide

/service               Helper service (future: signaling, OAuth)
/scripts               Development and initialization scripts
/docs                  Project-wide documentation
  /notes               Development notes and learnings

Key Configuration Files

  • CLAUDE - Instructions for AI assistants working on the codebase
  • README - Project overview
  • TESTING - Testing procedures

Concept Map

Core Principles

Technology Stack

  • Electron → Desktop framework (main + renderer + preload)
  • React → UI framework (v19, functional components)
  • TypeScript → Type safety throughout
  • Vite → Build tool and dev server
  • Tailwind CSS → Styling (v4)
  • RxDB → Local reactive database
  • libp2p → P2P networking library
  • WebRTC → P2P transport layer

Architecture Components

Documentation Patterns

Note Types

  • note-YYMMDD-[topic].md - Issue-specific learnings, problems solved
  • adr-YYMMDD-[decision].md - Architecture Decision Records
  • Session summaries - Milestone retrospectives
  • Concept explainers - Deep dives on specific technologies

Status Indicators

  • ✅ Resolved/Complete
  • 🔄 In Progress
  • ⚠️ Blocked
  • 🎓 Learning Phase

Quick Reference

Common Commands

# Initial setup
./scripts/dev-init.sh

# Development (app + test peer)
./scripts/start-dev.sh

# Testing
cd test-peer && npm start
cd app && npm run dev

# Building
cd app && npm run build
cd app && npm run typecheck

Key File Locations

  • Main process: app/src/main/main.ts
  • Renderer entry: app/src/renderer/App.tsx
  • IPC bridge: app/src/main/preload.ts
  • RxDB database: app/src/renderer/db/database.ts
  • Schemas: app/src/renderer/db/schemas.ts

For AI Assistants

When working on WhatNext:

  1. Start with: CLAUDE for development context
  2. Reference: whtnxt-nextspec for architectural decisions
  3. Check: Recent notes in /docs/05 notes/ for current state
  4. Document: New learnings following patterns in note-251110-libp2p-learning-roadmap

Active Development Areas (as of 2026-02-15)

  • ✅ P2P networking foundation (libp2p integration complete)
  • ✅ UI modernization (v0.0.0 polished)
  • ✅ Formal documentation (SRS + Architecture Design — see srs-whatnext, architecture-whatnext)
  • 🔄 Protocol implementation (next phase)
  • 🔄 Spotify adapter migration (Feb 2026 API changes — see the-walled-garden-cracks)
  • 🔜 RxDB replication over libp2p
  • 🔜 Import adapter architecture (service abstraction layer)
  • 🔜 Open metadata enrichment (MusicBrainz/ListenBrainz)

Last Updated: 2026-02-15
Documentation Version: v0.1.0