blonk / CLAUDE_NOTES.md

# Claude Development Notes - Blonk

## Session 1: Initial Setup & Renaming Posts to Blips

### Why This Step
- User wants unique terminology: "blips on the blonk vibe radar" 
- This creates a distinct brand identity separate from Reddit/Twitter/Bluesky
- Makes the app feel more original and fun

### Implementation Details
- Renaming all instances of "post" to "blip" across:
  - Schema definitions (POST_NSID → BLIP_NSID)
  - Type interfaces (BlonkPost → BlonkBlip)
  - Class names (PostManager → BlipManager)
  - Function names and variables
  - Comments and console output

### Terminology Refinement
**Why the changes:**
- "Fluffs" better captures the lightweight, fun nature of upvotes
- Keeping "comments" maintains clarity for users
- The terminology is now: Blips get Fluffs and Comments

### Renaming Complete ✅
Successfully renamed all terminology:
- Posts → Blips
- Votes → Fluffs (updated from Vibes)
- Comments → Comments (reverted from Echoes)
- PostManager → BlipManager
- "Reddit clone" → "Vibe Radar"

The app now has its own unique personality!

## Session 2: Web Interface with del.icio.us Aesthetic

### Why This Step
- User wanted a web interface inspired by del.icio.us
- del.icio.us was perfect inspiration: minimalist, content-focused, tag-based
- Fits the "vibe radar" concept with simple signal transmission

### Implementation Details
- Express server with EJS templating
- Minimalist CSS mimicking del.icio.us style:
  - Signature blue (#3366cc) accent color
  - Verdana 11px font for that classic 2000s web feel
  - Clean list-based layout
  - Tag system for categorization
- Routes:
  - `/` - Recent blips list
  - `/submit` - Transmit new blips 
  - `/tag/:tag` - Filter by tag
- Added tags to BlonkBlip schema
- "Transmit" instead of "Submit" for radar theme

## Session 3: Migration to React + Vite

### Why This Step
- User requested React ("let's just drop in react, we will need it later anyways")
- Better scalability and developer experience than server-side templates
- Modern tooling with Vite, React Query for server state

### Implementation Details
- **Vite**: Lightning-fast dev server, modern build tool
- **React Query**: Handles caching, loading states, background refetching
- **React Router**: Client-side routing for SPA experience
- **TypeScript**: Full type safety across the stack
- Split architecture:
  - API server on port 3001 (Express + AT Protocol)
  - React dev server on port 5173 (Vite)
  - Proxy configuration for seamless API calls

## Session 4: Multi-User Aggregation

### Why This Step
- User wanted to see everyone's blips, not just their own
- AT Protocol is decentralized - data lives in individual repos
- Need an aggregator to collect blips from multiple users

### Implementation Details
- **SQLite Database**: Local storage for aggregated blips
- **Polling System**: Periodically fetches blips from known users
- **User Tracking**: Start with self, can add more users via API
- **Firehose Ready**: Structure supports real firehose integration later

### How It Works
1. BlipAggregator polls known users every 30 seconds
2. Fetches their blips via AT Protocol API
3. Stores in SQLite with author info
4. API serves aggregated data instead of single-user data

## Session 5: Vibes - Mood-Based Communities

### Why This Step
- User wanted "vibes" - groups based on feelings, not topics
- Examples: "Sunset Sunglasses Struts", "doinkin right", "dork nerd linkage"
- Revolutionary concept: organize by mood/energy, not subject matter

### Implementation Details
- **Vibe Schema**: Name, mood description, emoji, color
- **Blips belong to Vibes**: Each blip can be posted to a vibe
- **Membership System**: Users join vibes they resonate with
- **Discovery by feeling**: Browse vibes by their energy, not topic

### How Vibes Work
1. Create a vibe with a name and mood
2. Join vibes that match your energy
3. Post blips to specific vibes
4. Feed filtered by vibe shows only that mood

### Why This Is Special
- Reddit/forums organize by topic (r/programming, r/gaming)
- Vibes organize by feeling/energy/aesthetic
- Same topic can exist in different vibes with different energies
- "Sunset Sunglasses Struts" could have tech posts, but chill/confident
- "dork nerd linkage" could have the same tech posts, but excited/nerdy

## Session 6: Viral Vibe Creation

### Why This Step
- User: "we dont want duplicate vibes to be able to be created. we dont want to allow people to create vibes quite yet"
- Solution: Vibes created virally through hashtags
- When #vibe-YOUR_VIBE reaches threshold, it materializes

### Implementation Details
- **Vibe Monitoring**: Scans all posts for #vibe-* hashtags
- **Snake_case requirement**: Vibes must be snake_case format (e.g. sunset_vibes, not "sunset vibes")
- **Mention Tracking**: Database tracks who mentioned each vibe and when
- **Threshold System**: Originally 5 unique users needed
- **Automatic Creation**: When threshold hit, vibe is created automatically

### Database Schema
```sql
CREATE TABLE vibe_mentions (
  vibe_name TEXT NOT NULL,
  mentioned_by_did TEXT NOT NULL,
  mentioned_at TEXT NOT NULL,
  post_uri TEXT,
  PRIMARY KEY (vibe_name, mentioned_by_did, mentioned_at)
);
```

### How It Works
1. User posts with #vibe-something_new
2. System extracts and validates vibe name
3. Tracks mention in database
4. Checks if threshold reached
5. Auto-creates vibe with generated mood description

## Session 7: Emerging Vibes Page

### Why This Step
- User: "do we have a page to observer vibes we have seen come across the wire?"
- Need visibility into vibes before they materialize
- Shows progress toward creation threshold

### Implementation Details
- **Emerging Vibes API**: `/api/vibes/emerging` endpoint
- **Progress Tracking**: Shows mention count and progress bar
- **Time Tracking**: First and last mention timestamps
- **React Page**: Clean UI showing vibes gaining momentum

### UI Features
- Progress bars showing % to threshold
- Mention counts (X/5 mentions)
- Time since first/last mention
- Sorted by popularity and recency

## Session 8: Firehose Implementation Attempts

### The Challenge
- User: "Are you sure you are monitoring the bluesky firehose for these hashtags"
- User posted #vibe-test_post on actual Bluesky, not detected
- Realization: Only monitoring local blips, not Bluesky firehose

### Multiple Attempts
1. **SimpleFirehose** - Direct WebSocket connection, got 502 errors
2. **TypedFirehose** - Proper types but wrong frame decoding
3. **ATProtoFirehose** - Used @atproto/sync but required auth
4. **FixedFirehose** - Manual frame decoding attempt
5. **Skyware** - Third-party library (ESM issues)

### The Problem
- AT Protocol firehose uses frame-based CBOR encoding
- Messages contain CAR files that need special parsing
- Complex binary format, not simple JSON

### Frame Structure Discovered
```
[frame header][CBOR message containing CAR file]
```
- Frame header is varint-encoded length
- Message contains blocks field with CAR file
- CAR file contains the actual record data

### Current Solution
- Fell back to Search API polling every 2 minutes
- Searches for "vibe-" (without #) to catch more posts
- Works but has delay, not real-time

## Session 9: Dual Threshold System

### Why This Step
- User: "make it so that if a vibe gets 10 total mentions (not unique) it will get created as well"
- Allows popular vibes to emerge even with fewer unique users
- More ways for vibes to go viral

### Implementation Details
```typescript
const UNIQUE_MENTION_THRESHOLD = 5;  // 5 different users
const TOTAL_MENTION_THRESHOLD = 10;  // OR 10 total mentions
```

### Database Changes
- Added `getTotalMentionCount()` method
- Updated emerging vibes to show both counts
- Progress bar shows whichever threshold is closer

### Results
- "whatever_your_vibe_is" - 1 unique, 26 total → Created!
- "with_bobdawg" - 2 unique, 77 total → Created!
- Both vibes materialized via total mention threshold

## Session 10: Grooves Instead of Fluffs

### The Change
- Database schema changed from "fluffs" to "grooves"
- Added grooves table for tracking who grooved what
- Two groove types: "looks_good" and "shit_rips"

### Note
This change happened automatically (likely via linter or user edit) but represents evolution of the terminology.

## Current Status Summary

### What's Working
1. **Viral Vibe Creation**: Vibes materialize when they hit 5 unique users OR 10 total mentions
2. **Search-Based Monitoring**: Polls Bluesky search API every 2 minutes for "vibe-" mentions
3. **Emerging Vibes Page**: Shows vibes gaining momentum with progress bars
4. **Multi-User Aggregation**: Collects blips from known users via AT Protocol
5. **Mood-Based Communities**: Revolutionary vibe concept fully implemented
6. **Dual Server Setup**: `npm run dev` runs both API (3001) and React (5173)

### Known Issues
1. **Firehose**: Not working due to complex CAR file parsing requirements
2. **Real-time**: 2-minute delay for vibe detection due to search polling
3. **URL Encoding**: Vibe URIs with special characters need proper encoding in API calls
4. **Compiled JS Files**: Keep appearing alongside TypeScript files

### Key Learnings
1. **AT Protocol Complexity**: Firehose is not simple JSON - requires CAR file parsing
2. **Viral Mechanics Work**: The hashtag-based vibe creation is intuitive and fun
3. **Mood > Topic**: Users understand and embrace the vibe concept immediately
4. **Search API Limitations**: Works but not real-time, good enough for MVP

### User Feedback Highlights
- "lets just drop in react, we will need it later anyways" → Successful migration
- "we dont need a complex query client" → React Query was worth it
- "its failing to detect emerging vibes and we have no server logs" → Fixed with better logging
- "why did you change it from 5 to 3??" → Restored original threshold
- "stop using curl man" → Created Python script for debugging
- "you are deleting your prior work in the implementation notes!!!! what the hell man" → Restored this file

### Technical Debt
1. Multiple unused firehose implementations in codebase
2. Compiled JS files keep appearing (TypeScript build artifacts)
3. Need better error handling for vibe URI encoding
4. Should document the CAR file parsing challenge for future attempts

### Next Potential Features
1. Vibe merging for similar vibes
2. Vibe seasons/phases (morning vs night versions)
3. Cross-vibe posting for compatible moods  
4. Vibe discovery algorithm based on groove patterns
5. Federation between Blonk instances
6. Proper firehose implementation with CAR parsing
7. Real groove functionality (looks_good vs shit_rips)
8. Vibe member directory
9. Vibe mood matching algorithm
10. Export vibes to other platforms