Backend API: Complete Data & Future Roadmap

[tacticalnoot]

Problem

The frontend downloads a ~25MB JSON snapshot because the backend /smols endpoint returns incomplete data. This causes:

• ❌ Cloudflare Pages 25 MiB file limit errors
• ❌ Slow initial page load (every user downloads 25MB)
• ❌ Stale data (snapshot requires manual updates)

Current Symptoms

Many items from /smols return:

• Tags: [] (empty)
• Address: null
• Minted_By: null

---

Phase 1: Immediate Fix (Remove 25MB Snapshot)

1.1 Enhanced GET /smols

Return complete, flat data for each smol:

{
  "Id": "abc123",
  "Title": "Cosmic Vibes",
  "Address": "GABC...XYZ",
  "Creator": "GABC...XYZ",
  "Minted_By": "GDEF...123",
  "Mint_Token": "CDXYZ...",
  "Tags": ["electronic", "chill"],
  "Plays": 142,
  "Views": 89,
  "Created_At": "2025-12-15T10:30:00Z",
  "Lyrics": "Stars align..."
}

Key: If Tags is empty, populate from wherever styles/genres are stored.

1.2 New: GET /smols/tags

Aggregated tag counts (so frontend doesn't download all songs for tag cloud):

{ "tags": [{ "tag": "electronic", "count": 245 }] }

1.3 New: GET /smols/artist/:address

Songs filtered by wallet for artist pages:

{
  "discography": [...],
  "minted": [...],
  "collected": [...],
  "stats": { "publishedCount": 42, "mintedCount": 15, "collectedCount": 8 }
}

Logic:

• discography = Address === :address OR Creator === :address
• minted = discography where Mint_Token exists
• collected = Minted_By === :address BUT Address !== :address

---

Field Reference

Field	Description
Id	Song UUID
Title	Display title
Address	Publisher wallet (for tipping)
Creator	Original creator wallet
Minted_By	Who minted/collected this
Mint_Token	Stellar smart contract token
Tags	Genre tags
Lyrics	Full lyrics text
Plays/Views	Counts
Created_At	ISO timestamp

---

Phase 2: Future Roadmap

Discovery & Engagement

Endpoint	Purpose
GET /smols/trending	Time-decayed popularity
GET /smols/similar/:id	Recommend songs with similar tags
GET /smols/new	Latest drops with pagination
GET /search?q=...	Full-text search

User Features

Endpoint	Purpose
GET /user/:address/history	Listening history
GET /user/:address/playlists	User-created collections
POST /user/:address/follow	Follow artists

Artist Analytics

Endpoint	Purpose
GET /artist/:address/stats	Plays over time, top tracks
GET /artists/top	Leaderboard

Real-Time

Endpoint	Purpose
WS /activity/mints	Live mint stream
GET /tokens/prices	Batch token price lookup

---

Success Criteria

Phase 1 Complete = Frontend deletes 25MB snapshot file, Cloudflare deploys successfully

[tacticalnoot]

Implementation Note:
Feel free to name this endpoint whatever you want or architect the solution however you see fit (e.g., ElasticSearch, SQL View, etc). The specific endpoint names above are just suggestions.

The Critical Requirement is simply:

1. It must be Comprehensive: One source of truth for ALL songs (replacing the fragmented snapshot/live split).
2. It must be Live: synced with mint events.
3. It must be Universal: usable for Radio, Artist pages, and Tag exploration alike.

Solve that, and you can build it however you like! 🚀

[tacticalnoot]

📊 Universal Song Schema

To power all frontend views (Radio, Artist Discography, Tag Explorer, Search) without fragmentation, the GET /songs index must return objects matching this comprehensive contract.

This flattens data previously split between D1, KV, and Workflow state.

interface UniversalSong {
  // Core Identity
  Id: string;           // The unique hash ID (e.g., "1.2.3")
  Title: string;        // Display Title
  Address: string;      // Artist Wallet Address (for /artist/[address] routing)
  Creator: string;      // Artist Display Name
  
  // Audio & Visuals
  Audio: string;        // Full URL to mp3/wav
  Cover: string;        // Full URL to cover image (or base64 if legacy)
  Song_1?: string;      // Legacy audio path (fallback)
  
  // Metadata & Discovery
  Description?: string; // Prompt text / description
  Tags: string[];       // Array of tags (e.g. ["lofi", "chill"]) - CRITICAL for Radio
  Lyrics?: {
    plain: string;      // Plaintext lyrics
    synced?: string;    // JSON/LRC if available
  };
  
  // Blockchain Life Cycle
  Mint_Token?: string;  // Token Contract Address (if minted)
  Minted_By?: string;   // Address of the user who minted it (Vital for "Collected" tab)
  Mint_Amm?: string;    // AMM Contract Address
  
  // Metrics (Real-time Liveness preferred)
  Plays: number;        // Global play count
  Views: number;        // Detail page view count
  Unique_Minters?: number; // Number of unique wallets holding the token
  
  // System
  Created_At: string;   // ISO Timestamp (Vital for "Fresh Drops")
  Ver: number;          // Schema version
}

Critical Implementation Details

1. Tags Normalization: Ensure Tags is always an array, even if stored as a CSV string in D1.
2. Text Search: Title, Creator, and Tags must be indexed for partial matching.
3. Mint State: Minted_By is the key to the "Collected" tab. If a user connects wallet X, we query GET /songs?minted_by=X.
4. Sort Keys:
   • sort=newest -> Created_At DESC
   • sort=popular -> (Plays + Views) DESC
   • sort=shuffle -> Random seed

[tacticalnoot]

Updated: Concrete API Requirements to Remove 25MB Snapshot

Following up on the discussion with Tyler - here are the specific field requirements:

---

The Core Problem

Many items from /smols currently return incomplete data:

• Tags: [] (empty)
• Address: null
• Minted_By: null

This forces the frontend to maintain a 25MB fallback file.

---

Required Response Shape (per smol)

{
  "Id": "abc123",
  "Title": "Cosmic Vibes",
  "Address": "GABC...XYZ",
  "Creator": "GABC...XYZ",
  "Minted_By": "GDEF...123",
  "Mint_Token": "CDXYZ...",
  "Tags": ["electronic", "chill"],
  "Plays": 142,
  "Views": 89,
  "Created_At": "2025-12-15T10:30:00Z",
  "Lyrics": "Stars align..."
}

Key: If Tags is empty, populate from wherever styles/genres are stored.

---

New Endpoints Needed

GET /smols/tags

Aggregated tag counts (so frontend doesn't download all songs for tag cloud):

{ "tags": [{ "tag": "electronic", "count": 245 }] }

GET /smols/artist/:address

Songs filtered by wallet:

{
  "discography": [...],
  "minted": [...],
  "collected": [...],
  "stats": { "publishedCount": 42, "mintedCount": 15, "collectedCount": 8 }
}

Logic:

• discography = Address === :address OR Creator === :address
• minted = discography where Mint_Token exists
• collected = Minted_By === :address BUT Address !== :address

---

Field Reference

Field	Description
Id	Song UUID
Title	Display title
Address	Publisher wallet (for tipping)
Creator	Original creator wallet
Minted_By	Who minted/collected this
Mint_Token	Stellar smart contract token
Tags	Genre tags
Lyrics	Full lyrics text
Plays/Views	Counts
Created_At	ISO timestamp

---

Success = Frontend deletes 25MB snapshot file

[tacticalnoot]

🔮 Future API Roadmap (Brainstorm)

Beyond the immediate snapshot removal, here are potential endpoints to consider as the platform grows:

Discovery & Engagement

Endpoint	Purpose
GET /smols/trending	Time-decayed popularity (recent plays + mints)
GET /smols/similar/:id	Recommend songs with similar tags
GET /smols/new	Latest drops with pagination
GET /search?q=...	Full-text search (titles, lyrics, tags)

User Features

Endpoint	Purpose
GET /user/:address/history	Listening history
GET /user/:address/playlists	User-created collections
POST /user/:address/follow	Follow artists

Artist Analytics

Endpoint	Purpose
GET /artist/:address/stats	Plays over time, top tracks
GET /smols/:id/stats	Per-song analytics
GET /artists/top	Leaderboard

Real-Time

Endpoint	Purpose
WS /activity/mints	Live mint stream
GET /tokens/prices	Batch token price lookup

---

Priority Suggestion:

1. 🔥 /smols/trending - Drives engagement
2. 🔍 /search - Essential as catalog grows
3. 🎯 /smols/similar/:id - Powers "up next" in radio

[tacticalnoot]

🚀 Smol Platform Overhaul — Backend Data Requirements (Relay)

Relaying the comprehensive backend data requirements discussed for the platform overhaul — with the goal of eliminating fragile local snapshot dependencies and enabling richer discovery + mobile-native experiences.

---

1) 🧱 Unified Smols List Data (Complete List Payload)

To fully replace the local snapshot, the list response must be complete.
Each Smol object should include:

✅ Core Identity

• Id
• Title
• Address (Contract Address)
• Creator (Wallet)
• Minted_By (Owner Wallet)
• Mint_Token (Token ID)

🏷️ Metadata

• Tags
• Created_At
• Lyrics

❤️ Engagement Stats

• Likes (global count)
• Plays
• Views

---

2) 🎤 Artist Profile Data (By Wallet)

For any given artist/user address, the API must return verifiable profile sections:

📀 Minted (Discography)

• Definition: all smols where Creator == Address
• Shows everything the artist has created/published, regardless of current owner/minted state.

🧺 Collected

• Definition: all smols where Minted_By == Address AND Creator != Address
• Shows smols the user owns/collected from other artists.

---

3) 📊 Profile Stats (Summary Counts)

Provide summary counts so the UI can show badges/stats without fetching thousands of records:

• Total_Created (count)
• Total_Collected (count)

---

4) 🌙 Dreamboard — Advanced Algorithmic & Deep Data Endpoints

Future “big data” endpoints to power Spotify/Pandora-style discovery, intelligence, and network effects.

✅ Core Rec / Graph / Analytics Endpoints

🤝 GET /recommendations/collaborative

• Input: User ID, liked song IDs
• Output: list of Smols
• Logic: “Users who liked these songs also liked…” (item-to-item CF / matrix factorization)

🎧 GET /recommendations/sonic-similarity

• Input: target Smol ID
• Output: list of Smols with similar audio features
• Logic: distance search over extracted features (BPM, key, energy, danceability, MFCC vectors, etc.)

⏭️ GET /recommendations/next-track

• Input: current session history (last ~5 songs played)
• Output: probability-ranked next songs
• Logic: Markov chains or session-model prediction (RNN/Transformer) to maintain “flow”

🕸️ GET /graph/affinity/artist

• Input: artist address
• Output: network graph of related artists
• Logic: co-occurrence from likes/collects (artists frequently collected together)

🧠 POST /vectors/generate

• Input: audio file or lyrics text
• Output: high-dimensional embedding vector
• Logic: semantic search (e.g., query “sad robot love song” even if not in title)

📈 GET /analytics/global-pulse

• Input: timeframe
• Output: trending clusters, “movers & shakers” (velocity of likes/plays)
• Logic: stream analysis of engagement events

---

🧨 AI-Powered “Next Level” Dreamboard Ideas (Add-On Endpoints)

🧑‍🚀 POST /ai/dj/queue

• Input: user context (mood prompt, current queue, last 20 plays, skips, session length)
• Output: curated queue + reasons per track (short natural-language)
• Value: “AI DJ” that feels intentional — not random.

🧬 GET /ai/taste/embedding

• Input: user ID
• Output: user “taste vector” + top dimensions (interpretable labels)
• Value: portable taste profile for recs, personalization, and “taste evolution” over time.

🧠 POST /ai/semantic-search

• Input: natural language query (“sad robot love song with distorted bass”)
• Output: ranked Smols + matched signals (lyrics similarity, sonic similarity, tags)
• Value: search that works even when metadata is messy or missing.

🗺️ GET /ai/taste-map

• Input: timeframe + optional filters
• Output: clustered “map” of genres/vibes + representative songs
• Value: a visual explore mode (“constellations” / “galaxy” browsing).

🏷️ POST /ai/tags/suggest

• Input: Smol ID (or audio+lyrics)
• Output: suggested tags + confidence + “why”
• Value: fixes tag quality, improves discovery, reduces manual tag chaos.

🧹 POST /ai/metadata/normalize

• Input: raw metadata (title, tags, artist name variants)
• Output: normalized metadata + canonical forms
• Value: dedupes tag spam, merges synonyms, cleans inconsistent naming.

🕵️ GET /ai/anomaly-detection

• Input: timeframe
• Output: suspicious engagement patterns + confidence
• Value: protects the ecosystem from botted likes/plays and manipulation.

🧾 POST /ai/session-recap

• Input: session history (tracks played, liked, tipped, skipped)
• Output: “Your Session” summary (vibes + top discoveries + shareable card text)
• Value: makes listening sessions shareable + sticky.

🔥 GET /ai/trending-predictions

• Input: timeframe + horizon (e.g., next 24h / next 7d)
• Output: predicted movers + confidence bands
• Value: “next up” radar — helps surface emerging artists earlier.

🎛️ POST /ai/radio/build

• Input: seed(s) (song IDs / artist IDs / prompt / tags) + constraints (energy, tempo range, novelty)
• Output: a generated station definition + queue + fallback logic
• Value: reproducible radio stations (“save this station”, “share this station”).

🧩 GET /ai/creator-insights

• Input: creator address + timeframe
• Output: what’s working (retention, skip points, tag reach, repeat listeners)
• Value: gives artists actionable feedback loops without requiring them to be data nerds.

🧵 POST /ai/playlist/title-and-cover

• Input: playlist track list + optional vibe prompt
• Output: playlist name ideas + short description + cover prompt tokens
• Value: instant “polish” for playlists and stations (viral-friendly).

---

5) 🎮 New App Idea — “Kale or Fail” (React Native Experiment)

Proposal: add a Games menu item to pioneer richer sentiment signals + on-chain payments ($KALE).

🧲 Concept

• Tinder-style discovery interface for songs.

🕹️ Mechanics

• Swipe Right: TIP the artist (10 / 100 / 1000 $KALE or Custom)
• Swipe Left: SKIP the song

🧬 Deep Data Value

• Explicit sentiment: money-backed “super likes” vs active skips = high-confidence training data
• Payment streams: test real on-chain artist revenue loops
• Discovery flywheel: high-velocity feedback loop for new drops

---

6) ⚡ Kale or Fail — Architecture & Speed (“3-Second Rule”)

Technical requirements to achieve zero-friction swipe → pay UX.

🧩 Game API Endpoints

• GET /game/feed
  • Fetches a smart stack of un-rated songs
  • ✅ Optimization: prefetch audio/images for next 5 cards for instant transitions
• POST /game/swipe
  • Records the interaction + payment proof
  • ✅ Stores sentiment (tip/skip) and links the blockchain transaction ID for verification

💸 Fast Payment Logic (The 3-Second Rule)

• Session Keys (Pre-Auth):
  • user approves a “game budget” once (example: 5000 $KALE)
  • app creates a temporary local signer limited to that budget
• Zero-Confirm UI (Optimistic UX):
  • swipe right → instantly play “cha-ching” + show next card
  • background: sign + submit Stellar transaction asynchronously
• Result:
  • uninterrupted swiping flow while payments settle on-chain in ~3–4 seconds ✅

---

[tacticalnoot]

📦 Smol Platform Overhaul — Backend Data Requirements (Non-Prescriptive)

This document lists data fields, query shapes, and example endpoint inputs/outputs that may be needed to support the platform overhaul.
It describes what information the frontend/product may rely on, without describing implementation details.

---

1) 🧱 Unified Smols List Data (Complete List Payload)

A smols list response may need to be sufficient to replace any local snapshot dependency.
Each smol object may need to include:

✅ Core Identity

• Id
• Title
• Address (Contract Address)
• Creator (Wallet)
• Minted_By (Owner Wallet)
• Mint_Token (Token ID)

🏷️ Metadata

• Tags
• Created_At
• Lyrics

❤️ Engagement Stats (Aggregates)

• Likes (global count)
• Plays
• Views

🧩 Optional: Media / Display Fields (if applicable)

• Image_Url (or equivalent image reference)
• Audio_Url (or equivalent audio reference)
• Duration (seconds)
• Explicit (boolean, if used for filtering)

---

2) 🎤 Artist Profile Data (By Wallet)

For a given wallet address, artist/profile views may need queryable datasets for:

📀 Minted (Discography)

• Selection rule: all smols where Creator == Address
• Meaning: items the artist created/published, regardless of current owner/minted state

🧺 Collected

• Selection rule: all smols where Minted_By == Address AND Creator != Address
• Meaning: items the user owns/collected from other artists

🔎 Optional: Additional Profile Lists (if applicable)

• Liked smols (if likes are user-address-scoped)
• Play history / recently played (if the product displays it)
• User-created playlists / stations (if stored server-side)

---

3) 📊 Profile Stats (Counts / Summary)

Profile pages may need summary counts to display totals without requiring full record fetches:

• Total_Created (count)
• Total_Collected (count)

Optional additional aggregates (if displayed):

• Total_Likes_Received (count)
• Total_Plays (count)
• Total_Tips_Received (amount and/or count, if tips exist)

---

4) 🎮 “Kale or Fail” (Game/Discovery Mode) — Data Requirements

A swipe-based discovery mode may need data support for:

🧲 Feed Data (Cards)

A per-user or per-session feed may need:

• A list of candidate smols (IDs + the minimum fields needed to render/play a card)
• Per-item state flags (examples):
  • Already_Rated (boolean)
  • Already_Tipped (boolean)
  • Already_Skipped (boolean)
• Optional “why this was shown” metadata (examples):
  • Reason_Code (e.g., similar-to-liked, trending, new-drop, etc.)
  • Score (numeric)

🕹️ Interaction Record Data (Swipe Events)

A record of per-song outcomes may need:

• User_Address (or user ID)
• Smol_Id
• Outcome (e.g., TIP or SKIP)
• Optional tip fields:
  • Tip_Amount
  • Tip_Token (e.g., $KALE)
• Optional blockchain payment reference:
  • Tx_Id (or equivalent proof reference)
  • Payment_Status (e.g., pending/confirmed/failed, if surfaced)

🧬 Sentiment / Training Signals

If used for discovery models, events may need:

• Explicit positive/negative signals per track (tip vs skip)
• Association to session context (examples):
  • Session_Id
  • Timestamp
  • Position_In_Session (card index)
• Optional UX signals (if tracked):
  • Listen_Seconds_Before_Swipe
  • Replay_Count
  • Mute/Unmute (boolean)

---

5) 🌙 Dreamboard — Algorithmic & Deep Data Endpoints (Inputs & Outputs)

These are example endpoint shapes that may be needed to support discovery, similarity search, and analytics.

🤝 Recommendations: Collaborative

GET /recommendations/collaborative

• Input: user identifier, liked smol IDs
• Output: list of smols (+ optional scores)

🎧 Recommendations: Sonic Similarity

GET /recommendations/sonic-similarity

• Input: target smol ID
• Output: list of smols + similarity score or ordering
• Associated data (per smol, where available):
  • audio feature representation (e.g., BPM, key, energy)
  • audio embeddings (vector ID + model/version label)

⏭️ Recommendations: Next Track

GET /recommendations/next-track

• Input: recent session history (e.g., last N smols played)
• Output: ranked list of next smols (+ probabilities/scores if present)

🕸️ Graph: Artist Affinity

GET /graph/affinity/artist

• Input: artist address
• Output: related artists graph (nodes/edges + weights)

🧠 Vectors / Embeddings Generation

POST /vectors/generate

• Input: audio file and/or lyrics text and/or smol ID
• Output: vector embedding reference + metadata (dimension, model/version label)

📈 Analytics: Global Pulse

GET /analytics/global-pulse

• Input: timeframe
• Output: trending items/clusters + growth/velocity metrics

Optional analytics outputs (if used):

• Top_New_Drops (time-windowed)
• Retention_By_Segment (aggregate buckets)
• Skips_By_Track (aggregate)

---

6) 🧠 Dreamboard — AI-Powered Additions (Data Needs)

These capabilities may require additional data fields or endpoints.

🔎 Natural Language Search Over Smols

POST /ai/semantic-search

• Input: natural language query
• Output: ranked smols + matched signals (lyrics similarity, tag match, sonic similarity)
• Optional output metadata:
  • per-result Score
  • per-result Match_Breakdown

🏷️ Tag Suggestions / Enrichment

POST /ai/tags/suggest

• Input: smol ID and/or audio and/or lyrics
• Output: suggested tags + confidence scores

🧹 Metadata Normalization

POST /ai/metadata/normalize

• Input: raw metadata fields (title/tags/artist variants)
• Output: normalized fields + canonical forms + confidence scores

🧬 User Taste Profile Representation

GET /ai/taste/embedding

• Input: user identifier
• Output: user taste embedding/vector + model/version label
• Optional:
  • “taste snapshot” timestamps for change over time

🎛️ Curated Queue Output (AI DJ / Station)

POST /ai/dj/queue

• Input: user identifier + optional session context + optional constraints
• Output: ordered queue + per-track scores/labels
• Optional:
  • short per-track Reason strings (if displayed)

🔥 Trending Forecast Output

GET /ai/trending-predictions

• Input: timeframe + horizon
• Output: predicted movers + confidence scores/bands

🧾 Session Summary Output (Shareable)

POST /ai/session-recap

• Input: session history (plays/likes/tips/skips)
• Output: structured recap object (highlights, top discoveries, summary text fields)

🧩 Creator Insights Output

GET /ai/creator-insights

• Input: creator address + timeframe
• Output: engagement summary metrics + retention/skip-style aggregates

🕵️ Integrity / Manipulation Signals

GET /ai/anomaly-detection

• Input: timeframe
• Output: anomalous engagement signals + confidence scores + affected entities

---

7) ⚡ Kale or Fail — UX Timing / Payment State Data (If Surfaced)

If the product displays fast swipe transitions with on-chain payments, data that may be needed includes:

💳 Budget / Authorization References (If Used)

• A reference to a per-session authorization or budget (identifier + limits)
• Remaining budget / spent amount (if shown)
• Expiration / session end fields (if relevant to UI)

🧾 Payment Lifecycle State (Per Tip)

• Tx_Id (or equivalent payment reference)
• Status (pending/confirmed/failed)
• Submitted_At, Confirmed_At (timestamps, if displayed)
• Failure metadata (reason code/message, if surfaced)

🔁 Reconciliation / Consistency Fields

• Ability to query tip records by:
  • user
  • smol ID
  • session ID
  • timeframe
• A stable idempotency identifier for swipe events (if duplicates are possible)

---