Skip to content

PodCommons v1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@wfryer wfryer released this 21 May 09:01
· 14 commits to main since this release
v1.0.0
bf6f24e

PodCommons v1.0.0

The first official release of PodCommons — an open-source community podcast discovery engine built with React, Firebase, and Gemini AI.

Live instance: https://podcasts.wesfryer.com

What is PodCommons?

PodCommons is a self-hostable podcast discovery platform that combines personal curation with community features and AI-powered episode analysis. The core idea: your listening history and taste preferences should drive what you discover next, not a black-box algorithm you don't control.

Built as a forkable, open-source project so educators, communities, and podcast enthusiasts can deploy their own instance and curate podcasts for their specific audiences.

v1.0.0 Highlights

AI-Powered Episode Analysis

Every episode is analyzed by Gemini 2.5 Flash at import time, generating topic tags from a controlled vocabulary, a taste score (0-100) reflecting relevance to the curator's interests, and a one-sentence summary. Over 3,700 episodes were tagged in the initial database at a cost of less than $2 USD.

Discover Algorithm

The Discover tab surfaces episodes using a weighted ranking formula combining AI taste score, recency, community engagement (likes, comments), and curator-defined feed weights. Users can adjust sliders to tune how much each factor influences their feed.

Topic Filter

Episodes are filterable by topic across 15+ categories including AI & Technology, Democracy & Civic, Education & Learning, Faith & Spirituality, Media Literacy, and Podcasting & Audio. Topic counts are displayed per category.

Community Features

  • User accounts via Google Auth with trust tiers (visitor, member, trusted, admin)
  • Episode likes and comments with auto-hyperlink detection
  • Discussions tab for community conversation
  • Content flagging system for admin review
  • Invite code system for controlled community onboarding

Podcast Suggestion System

Any visitor can suggest a podcast via the Suggest page. Admins review suggestions in the Admin dashboard; approving a suggestion automatically adds the RSS feed and triggers an immediate AI-analyzed poll.

Admin Dashboard

Full admin interface with tabs for Feeds, Episodes, Users, Suggestions, Flags, and System settings. Includes manual RSS poll trigger, episode pruning tools, and stats overview.

RSS Polling Infrastructure

Two Firebase Cloud Functions handle feed polling: a scheduled function that runs every 4 hours and a manually-triggerable HTTP endpoint. New episodes are analyzed by Gemini at import time. A stats cache is written after each poll so the About page loads instantly.

Episode Pruning

Configurable pruning script (pruneEpisodes.mjs) keeps the database lean by removing episodes older than N days that have no community engagement, while always preserving first-party podcast episodes and any episode with likes or comments.

About Page

Live stats (podcast count, episode count, member count, likes) served from a Firestore cache updated with each poll. Includes an introductory video and open-source fork invitation.

Tech Stack

Layer Technology
Frontend React 18, Vite, Tailwind CSS
Database Firebase Firestore
Auth Firebase Auth (Google)
Hosting Firebase Hosting
Backend Firebase Cloud Functions (Node.js)
AI Analysis Google Gemini 2.5 Flash

First-Party Podcasts (Curator's Own Shows)

This instance curates four first-party podcasts by Wes Fryer:

  • EdTech Situation Room
  • Speed of Creativity
  • Heal Our Culture
  • Wes & Shelly Share

Database at Launch

  • 408 podcasts indexed
  • 3,301 episodes with AI topic tags and taste scores
  • Gemini 2.5 Flash analysis on all episodes

Forking and Self-Hosting

PodCommons is designed to be forked. See SETUP.md for full deployment instructions covering Firebase project creation, environment variables, Firestore security rules, Cloud Function deployment, and first-party podcast configuration.

The codebase is structured so you can replace the curator's taste profile and first-party podcasts with your own in a single configuration file.

MIT License — fork it, modify it, deploy it for your community.

Known Issues / Roadmap (v1.1)

  • Discussions tab bug: shows all podcasts rather than filtering to only those with actual comments -- needs a Firestore query fix to only return podcasts/episodes where comment count > 0
  • Discussions tab UX redesign: flip the layout so the comment text is the primary element (headline), with the episode it belongs to shown below it indented -- makes community contributions the focus rather than podcast metadata; similar to a Mastodon or Reddit reply thread pattern
  • Admin "Trust User" button not functional (Firestore rules fix needed)
  • Manual "Add Feed" button missing from Admin Feeds tab (workaround: addFeed.mjs script)
  • Podcast title special character handling on import (apostrophes can mangle)
  • Maintenance mode (admin-toggled landing page for open-Firestore-rules windows)
  • Mobile UX audit pass
  • "Suggested by @username" badge on podcast pages
  • User-defined custom episode tags
  • Feedback link (Google Form) in footer

Acknowledgments

PodCommons was built across many late-night vibe coding sessions in April-May 2026 using Claude Sonnet as an AI pair programmer. Updates and reflections on the development process are shared at https://ai.wesfryer.com.

#podcommons

Assets 2
Loading