StreamPunk Implementation Plan

Executive Recommendation

Build StreamPunk as a Flutter app with a Cloudflare-first backend. Flutter is the best starting point because it supports iOS, Android, macOS, and Windows from one codebase, while still allowing native integrations for biometrics, push notifications, secure storage, subscriptions, and desktop packaging.

The first release should focus on discovery, favorites, ratings, personal watch/listen planning, a lightweight watch-party feature, and strong moderation controls. Keep the social layer intentionally small in version 1.0.0 because user-generated content is the part most likely to create app review, safety, moderation, and operational risk.

Recommended v1 stack: Flutter + Dart, Riverpod or Bloc for state management, Cloudflare Workers API, D1 for relational app data, R2 for media attachments and exports, Durable Objects for live watch-party rooms, Queues for moderation jobs, Turnstile for bot friction on web flows, OpenAI Moderation API or a comparable moderation provider, and RevenueCat for cross-store subscription entitlement management.

Product Purpose

StreamPunk helps people answer three everyday questions:

What should I watch or listen to next, and where is it playing? Search, browse, provider availability, favorites, ratings, recommendations, and random shuffle.
Where did I leave off and what is planned? Personal watchlist/listenlist, calendar-style scheduling, reminders, and history.
Who am I enjoying this with? Small watch parties with invitations, organizer controls, simple reactions, discussion boards, and moderated comments.

The target user includes people who struggle with modern technology, so the product should avoid clutter, jargon, hidden gestures, and dense settings. The app should feel like a friendly organizer, not another social network asking for constant attention.

Version 1.0 Scope

Include in 1.0.0	Defer Until Later
Single-account user model, account creation, login, MFA, biometric unlock, profile basics, privacy settings.	Household/family profiles, public creator profiles, follower feeds, algorithmic social timelines.
Search and discovery for movies, TV, podcasts, genres, providers, and basic availability.	Deep streaming-platform integrations that require complex licensing or provider partnerships.
Favorites, watchlist/listenlist, completed history, authenticated-user star ratings, comments, and feedback.	Full recommendation engine training pipeline. Start with rules plus provider metadata.
Random shuffle based on favorites, prior ratings, availability, and blocked genres.	Complex AI personality matching or opaque ranking that is hard to explain to users.
Small general-topic watch parties such as “Rom-Com Lovers” or “Sci-Fi Club,” with invite/request access, organizer approval, post board, reactions, reporting, blocking, and moderation queue.	Open-ended anonymous chat, live video, livestreaming, DMs, ephemeral stories, or TikTok-style feeds.
Subscription purchases through App Store and Google Play, plus desktop and public web app entitlement support.	Alternative mobile payment flows that could trigger app store rejection.

App review note: Apple and Google both scrutinize subscriptions and UGC. StreamPunk should ship with user reporting, blocking, moderation, published contact info, clear terms, clear subscription pricing, a reviewer demo account, and no placeholder screens.

User Experience Principles

Mobile First

Design the phone flow first, then adapt to tablet and desktop. Use large touch targets, readable type, bottom navigation, and predictable screen transitions.

Plain Language

Use labels like “Watch Later,” “Listening List,” “Party Board,” and “Pick for Me.” Avoid technical words like algorithm, metadata, ingestion, or provider unless inside admin tools.

Low Friction

Let users browse before subscribing where possible. Make account setup short. Ask for permissions only when needed and explain the benefit in one sentence.

Confidence

Every destructive action should have undo or confirmation. Moderated comments should explain status gently: “Only visible to you while it is being reviewed.”

Suggested Main Navigation

Home: “Pick for Me,” upcoming schedule, continue watching/listening, top suggestions.
Discover: Search, browse by genre, provider, mood, movie/TV/podcast type.
My List: Favorites, planned items, in progress, completed, hidden/disliked.
Parties: Your parties, invitations, discoverable parties, requests.
Profile: Account, subscription, privacy, security, blocked users, help.

Technology Stack

Layer	Recommendation	Why
Client app	Flutter + Dart	Single codebase for iOS, Android, macOS, Windows, and a functional web app; strong package ecosystem; good fit for Cursor development; easier to maintain than separate native clients.
Public web app	Flutter Web hosted on Cloudflare Pages, using the same backend APIs	Provides full StreamPunk functionality in a browser while reusing app code and API contracts. A separate marketing site can live beside it at `streampunk.app`.
State management	Riverpod, or Bloc if you prefer stricter event/state patterns	Riverpod is pragmatic and testable. Bloc is more formal. For a solo founder, Riverpod is probably friendlier.
Local storage	Drift/SQLite plus encrypted secure storage for secrets	SQLite handles offline lists and cached catalog data. Device keychains handle tokens and encryption keys.
Backend API	Cloudflare Workers with TypeScript	Excellent fit for API routes, low operational overhead, easy domain integration through Cloudflare, and scales from small usage without managing servers.
Primary database	Cloudflare D1	Relational SQLite-style data is a natural fit for users, favorites, parties, ratings, moderation queues, and subscriptions.
Realtime rooms	Cloudflare Durable Objects	Watch-party rooms need ordered membership and message state. Durable Objects are well suited to per-room coordination.
Background work	Cloudflare Queues + Cron Triggers	Use for moderation jobs, catalog refreshes, recommendation refreshes, email/push scheduling, and export jobs.
Object storage	Cloudflare R2	Store generated exports, moderation evidence snapshots, and future image attachments without egress-heavy storage costs.
Authentication	Auth0, Clerk, Stytch, Supabase Auth, or custom OIDC-compatible auth	Do not hand-roll authentication at first. Choose a vendor with MFA, passkeys, OAuth, account recovery, audit logs, and mobile SDK support.
Subscriptions	RevenueCat	Simplifies App Store, Google Play, and future desktop/web entitlements. Reduces receipt-validation complexity.
AI moderation	OpenAI Moderation API, Cloudflare Workers AI classification, or a specialist moderation provider	AI should triage and hold questionable content, but humans need final review tools and audit trails.
Moderator alerts	Email first, then Slack and SMS/MMS through provider integrations	Human admins should be alerted when AI moderation needs help. Start with email because it is simple and auditable; add Slack and SMS/MMS for urgency.
Analytics	PostHog Cloud or privacy-conscious event analytics	Track product usage without collecting unnecessary personal data. Use minimal event payloads.

Media Data APIs

No single public API perfectly covers movies, TV, network schedules, streaming availability, and podcasts with commercial-friendly terms. Start with a layered approach and design a provider abstraction so services can change later. Version 1 should focus on the United States, Canada, and the United Kingdom while storing locale, country, language, provider-region, and translated-display fields so the product can expand into additional languages later.

Need	Recommended Source	Notes
Movie and TV metadata	TMDB, IMDb API, OMDb as fallback	TMDB is popular and accessible, but confirm attribution and commercial terms before launch. IMDb has an official commercial API through AWS Data Exchange. OMDb can be useful but should not be the only source for a paid app.
Streaming availability	Watchmode or JustWatch partner API	Availability data is commercially valuable and often paid. Watchmode has explicit commercial tiers. JustWatch requires partner integration and attribution rules.
Podcasts	Podcast Index API	Good starting point for podcast search and episode metadata. Review terms before commercial use.
Network TV schedules	TVMaze, Gracenote, or paid broadcast data providers	Network schedules are licensing-sensitive. Use a modest v1 goal: episode dates and show metadata before full channel-grid scheduling.

Implementation pattern: Create a backend service named catalog-provider with provider adapters. The Flutter app should never call external media APIs directly. This protects API keys, normalizes data, caches responses, and makes provider changes less painful.

Backend Architecture

The backend should be modular even if it begins as one Cloudflare Workers project. Use clear route groups and shared service modules.

API Gateway

Cloudflare Worker handling auth verification, request validation, rate limiting, and routing.

Catalog Service

Searches providers, normalizes movie/TV/podcast records, stores cached catalog records, and tracks provider attribution.

User Library Service

Favorites, lists, history, ratings, comments, hidden items, “not interested,” and shuffle preferences.

Watch Party Service

General topic group creation, invitations, membership, organizer roles, party board posts, reactions, reports, and approvals.

Moderation Service

AI triage, human review queue, auto-approve thresholds, audit logs, appeals, and policy rules.

Subscription Service

RevenueCat webhooks, entitlement state, trial status, app-review demo users, and subscription-gated features.

Suggested API Route Groups

/v1/catalog/search, /v1/catalog/items/:id, /v1/catalog/providers
/v1/me, /v1/me/favorites, /v1/me/library, /v1/me/schedule
/v1/items/:id/ratings, /v1/items/:id/comments
/v1/parties, /v1/parties/:id/posts, /v1/parties/:id/reactions
/v1/moderation/reports, /v1/admin/moderation
/v1/subscriptions/status, /v1/webhooks/revenuecat

Ecosystem And Feature Flows

These diagrams are intentionally high-level. They show how the StreamPunk ecosystem is organized and how the most important features move data through the client, backend, providers, moderation, and storage layers.

Ecosystem Overview

Native Apps iOS, Android, macOS, Windows built with Flutter.

Web App Full browser app hosted on Cloudflare Pages.

→

Cloudflare Edge DNS, TLS, WAF, rate limiting, Pages, Workers API.

Auth & Subscriptions MFA/passkeys/biometrics, RevenueCat entitlements.

→

StreamPunk API Catalog, library, ratings, parties, scheduling, moderation.

Background Work Queues, cron jobs, alerts, catalog refreshes.

→

Data Stores D1 relational data, R2 objects, Durable Objects rooms.

External Providers TMDB/IMDb, Watchmode/JustWatch, Podcast Index, AI moderation.

Feature Organization Map

Discover

Search media
Browse genres
Check where it is playing
Filter by services and region

Plan

Favorites
Watch/listen list
History
Schedule and reminders

Choose

Pick for Me
Explain recommendation
Respect dislikes and blocked genres
Prioritize available titles

Discuss

Ratings
Comments
Feedback
AI and human moderation

Gather

General themed parties
Invites and join requests
Organizer controls
Party board and reactions

Protect

Authenticated posting
MFA and biometric unlock
Reports and blocks
Admin alerts and audit logs

Discovery And Availability Data Flow

User

SearchesMovie, show, podcast, genre, mood, or provider.

→

Reviews ResultsSees title, type, rating summary, and where it is playing.

→

Takes ActionAdds to list, favorites, schedules, rates, or opens provider.

StreamPunk

Normalize QueryApply region, language, provider filters, and safe defaults.

→

Fetch Or CacheUse D1 cache first, then catalog provider adapters.

→

Return Unified ItemMerge metadata, availability, attribution, and user library state.

Providers

Metadata APIsTMDB, IMDb, OMDb, TV schedule sources.

→

Availability APIsWatchmode, JustWatch, provider-specific links.

→

Podcast APIsPodcast Index and episode feeds.

Pick For Me Shuffle Flow

User Taps Pick For Me Optionally chooses media type, time available, mood, or service.

→

Preference Filter Favorite genres, favorite titles, disliked items, blocked genres.

→

Availability Filter US/Canada/UK region and services the user can access.

→

Rank And Randomize Blend good matches with novelty so it feels fresh.

→

Result With Reason “Picked because you like sci-fi and it is on a service you have.”

Comment, Rating, And Moderation Flow

Logged-In User Creates rating, comment, reaction, or feedback.

→

API Validates Checks auth, entitlement, rate limits, and content rules.

→

AI Moderation Approve, reject, or escalate based on policy thresholds.

→

Human Review Admins receive alerts for cases that need help.

→

Publish Or Hold Approved content becomes visible; questionable content stays private.

Watch Party Flow

Create Theme Organizer starts a group such as “Rom-Com Lovers.”

→

Invite Or Discover Users receive invites or request access to discoverable parties.

→

Organizer Approves Organizer manages membership, roles, mutes, and removals.

→

Party Board Members post, react, suggest media, and plan watch/listen time.

→

Moderation Layer AI flags sensitive content; reports and admins handle edge cases.

Data Model

Start relational. Add search indexes, vector embeddings, or external search later only when the catalog grows large enough to justify it.

Table	Purpose
`users`	Stable user account record, display name, locale, account status, created date.
`user_security_settings`	MFA state, passkey metadata, biometric preference flag, recovery state. Do not store biometric data.
`media_items`	Normalized movies, shows, podcast series, podcast episodes, and future media types.
`media_provider_refs`	Provider-specific IDs for TMDB, IMDb, Watchmode, Podcast Index, etc.
`genres`, `media_genres`	Genre taxonomy and relationships.
`user_favorite_genres`, `user_favorite_media`	Personal preference signal for recommendations and shuffle.
`library_items`	Watch/listen state: planned, in progress, completed, paused, abandoned, hidden.
`schedule_entries`	User plans and reminders for media consumption.
`ratings`	User star ratings; enforce one rating per user per media item.
`comments`	Public item comments with moderation state.
`watch_parties`	Party name, description, visibility, organizer settings, related media item.
`party_members`	Membership, organizer role, invite/request status, mute/ban state.
`party_posts`, `party_reactions`	Discussion board content and reaction records.
`moderation_cases`	AI result, review state, reviewer action, policy reason, audit timestamps.
`reports`	User-submitted reports for comments, posts, parties, or users.
`subscription_entitlements`	Current plan, source store, renewal state, RevenueCat customer ID.
`audit_logs`	Security-sensitive and moderation-sensitive actions.

Security And Privacy

StreamPunk should collect the smallest amount of personal data needed to provide the service. Treat trust as a product feature.

Security Requirements

Use HTTPS everywhere. Enforce HSTS through Cloudflare.
Use a professional auth provider with MFA, passkeys, OAuth/social login if desired, account recovery, and compromised-password protection.
Use biometric unlock through local device APIs. Never send or store biometric data on the server.
Store access and refresh tokens in platform secure storage, not normal app preferences.
Encrypt sensitive data at rest where possible. For especially sensitive user preferences or private notes, consider application-level encryption with keys protected by the user account/device.
Protect API routes with JWT validation, authorization checks, request schema validation, per-user rate limits, and abuse detection.
Separate admin permissions from normal user permissions. Require MFA for all admin and moderator accounts.
Log security events, but avoid logging raw comment content, access tokens, PII, or provider secrets.
Rotate API keys and keep all provider credentials server-side in Cloudflare secrets.
Implement GDPR/CCPA-style export and delete workflows even before you are forced to.

Important wording: The correct term is usually PII, personally identifiable information, rather than PPI. The plan should treat names, email addresses, account identifiers, IP-derived location, subscription state, moderation history, and social graph data as sensitive.

Moderation Plan

AI moderation should protect users and reduce workload, but it should not be presented as final authority. Use a state machine so every public comment and party post has a clear path.

State	User Experience	Backend Behavior
`pending_ai`	“Only visible to you while it is being reviewed.”	Content is queued for AI moderation.
`approved`	Visible to intended audience.	AI confidence is safe or human approved it.
`needs_human_review`	Still visible only to author and moderators.	Moderator reviews policy category, context, and user history.
`rejected`	Author sees a clear reason and optional appeal flow.	Content remains stored for audit window, then deleted/anonymized according to policy.
`removed_after_report`	Public content disappears; reporter receives acknowledgement.	Moderator or automated rule acted after a report.

Required UGC Controls

Report content and report user actions on every public comment and party post.
Block user feature that prevents further interaction.
Party organizer tools: remove member, mute member, approve join request, appoint organizer, close party.
Human admin alerts when AI moderation needs help, starting with email and expanding to Slack, SMS/MMS, or another urgent notification channel.
Published support/contact address in the app and on the website.
Terms of Use and Community Guidelines accepted before posting UGC.
Admin moderation dashboard available before submitting to app stores.
Comments, ratings, reactions, feedback, party posts, and all other user-generated content must be limited to authenticated logged-in users.

Recommendation And Shuffle

Start explainable. Users who struggle with technology should understand why StreamPunk picked something.

Version 1 Rules

Prioritize favorite genres and favorite media similarity.
Boost items available on services the user says they have.
Boost highly rated items from the community, but avoid making popularity the only signal.
Downrank disliked, hidden, abandoned, or already completed items.
Respect content filters, blocked genres, and preferred media type.
Give the result a simple reason: “Picked because you like mystery shows and shorter episodes.”

Later AI Enhancements

Natural-language preference capture: “I want something cozy but not too long.”
Embeddings for media descriptions and user taste profiles.
Party-aware recommendations that find overlap among members.
Weekly digest of newly available content based on favorites.

Monetization

Because the app will sell subscriptions through app stores, keep mobile purchases inside Apple and Google billing systems. Use RevenueCat or a similar service to unify entitlements.

Tier	Possible Features
Free	Search, limited favorites, limited lists, basic ratings, one or two parties, basic shuffle.
Plus	Unlimited favorites/lists, reminders, advanced filters, richer shuffle, more parties, party recommendation matching.
Family/Household	Multiple profiles, shared watch planning, family-safe controls, household recommendations.

Subscription copy must be very clear: price, renewal period, trial conversion, cancellation path, and what features remain available without paying.

App Store Readiness

Create a demo reviewer account with realistic data, approved comments, pending comments, a sample watch party, and subscription state notes.
Build a web privacy policy at streampunk.app/privacy and terms at streampunk.app/terms before app submission.
Do not use copyrighted logos, posters, or provider assets unless the API/provider terms allow them and attribution is correct.
Avoid anonymous random chat. Parties should be invite-based or request-to-join with organizer controls.
Make report/block/moderation tools visible and functional in the submitted build.
Use official in-app purchase SDKs through Flutter plugins or RevenueCat. Do not mention external payment options inside the mobile app unless allowed by current regional rules and carefully reviewed.
Include support contact info and a way to delete an account.
Test on real iOS and Android devices, plus desktop smoke tests, before submitting version 1.0.0.

Implementation Roadmap

Phase 0: Foundation And Decisions

Choose auth provider, subscription provider, and initial media APIs.
Set version 1 launch region to the United States, Canada, and the United Kingdom, with English-first copy and database support for future translated fields.
Create brand basics: logo, color palette, typography, app icon, plain-language style guide.
Register Apple Developer and Google Play Console accounts.
Set up Cloudflare Pages for the public website and Cloudflare Workers for the API.
Draft Privacy Policy, Terms of Use, Community Guidelines, and moderation policy.

Phase 1: App Skeleton

Create Flutter project with mobile and desktop targets enabled.
Enable Flutter Web so the same app can be deployed as a full public-facing web app through Cloudflare Pages.
Add routing, state management, design system components, secure storage, API client, and environment config.
Build onboarding, login, logout, account settings, and biometric unlock.
Create skeleton screens for Home, Discover, My List, Parties, and Profile.

Phase 2: Backend MVP

Create Workers API project with TypeScript, request validation, auth middleware, error handling, and test harness.
Create D1 schema and migrations for users, catalog, favorites, ratings, comments, parties, moderation, and subscriptions.
Add provider adapters for first movie/TV source and first podcast source.
Add API caching and provider attribution fields.

Phase 3: Discovery And Lists

Implement search, item detail pages, genre browsing, favorite genres, favorite media, watch/listen status, and completed history.
Implement offline-friendly local cache for user library and recently viewed catalog records.
Add star ratings and comments with moderation state.

Phase 4: Scheduling And Shuffle

Build schedule entries, reminders, calendar-style list view, and push notification setup.
Implement the version 1 shuffle engine with reason text and a retry button.
Add provider/service filters so users can say which streaming services they have.

Phase 5: Watch Parties

Create general topic party creation, invite links, request access, organizer approval, and membership management.
Build party board posts, reactions, reports, blocks, mutes, and organizer removals.
Add Durable Object room handling if live updates are needed for party boards. Otherwise begin with polling and upgrade later.

Phase 6: Moderation And Admin

Integrate AI moderation provider for comments and party posts.
Build admin dashboard for pending cases, reports, user history, decisions, and audit logs.
Add human admin alerts for moderation cases that need help, beginning with email and then adding Slack and SMS/MMS as operational preferences become clear.
Define thresholds: auto-approve low-risk content, hold medium-risk content, reject or escalate high-risk content.

Phase 7: Subscriptions And Launch

Configure App Store and Google Play subscription products.
Integrate RevenueCat, webhook handling, and entitlement-gated features.
Run accessibility, privacy, security, and app-review readiness checks.
Submit TestFlight and internal Google Play testing builds, fix review feedback, then submit 1.0.0.

Development Setup

Cursor is a good fit for this project because it gives you AI-assisted editing while still working like a normal code editor. Xcode will still be required for iOS signing, simulators, and App Store submission.

Local Tools

Flutter SDK and Dart SDK.
Xcode, iOS Simulator, CocoaPods, and Apple Developer account when ready.
Android Studio for Android SDK, emulator, and Play tooling.
Node.js, pnpm, Wrangler CLI for Cloudflare Workers and D1 migrations.
GitHub private repository. The app does not need to be open source.

Suggested Repo Structure

/apps/streampunk_flutter for the Flutter client across iOS, Android, macOS, Windows, and web.
/apps/marketing_site for the public landing, privacy, terms, support, and app-review information pages.
/services/api for Cloudflare Workers TypeScript API.
/services/admin for moderation/admin web dashboard.
/packages/shared for shared schemas, API types, constants, and generated clients.
/docs for planning, policies, and app-review notes.

Settled Product Decisions

Version 1 supports single user accounts only. Household and family profiles are deferred for later.
Watch parties are general topic groups with themes such as “Rom-Com Lovers” or “Sci-Fi Club,” rather than only one-time groups tied to a specific title and time.
All commenting, rating, feedback, reactions, and party posting must be gated to authenticated logged-in users.
The initial launch region is the United States, Canada, and the United Kingdom, English-first, with architecture prepared for future multilingual support and AI-assisted translation.
A small group of human admins will review moderation escalations and should receive alerts through email first, with Slack and SMS/MMS as likely follow-on channels.
StreamPunk should include native apps and a public-facing web app with full functionality, all using the same backend APIs.

Source Notes

These are useful reference links for the first technical decisions. Re-check terms and policies before launch because they change.