## Overview Podia is a comprehensive digital product platform that empowers creators to build and sell online courses, memberships, digital downloads, webinars, and manage email marketing campaigns. This is a mature, production-grade Rails application serving as the backbone of a fully-remote team's SaaS business. **Repository Age**: 11+ years (started September 19, 2014) **Total Commits**: 81,964 **Commit Velocity**: 10,798 commits in the last year (~30 commits/day) **Codebase Size**: 24,779 Ruby files, 56,585 JavaScript/TypeScript files **Active Development**: 565 remote branches, highly collaborative workflow ## Architecture Podia follows a modular monolithic architecture built on Rails, with distinct sections serving different user personas: ### Application Sections 1. **CMS (Content Management System)** - Primary work area for creators to manage their business - Controllers in `app/controllers/cms/` - Manages accounts, websites, emails, products, and customers - Accessed via `app.podia.com` or `app.local.podia.tech:3000` in development 2. **Hub (Community Platform)** - Central hub for customers to interact with content and each other - Under active development (major focus in recent commits) - Controllers in `app/controllers/hub/` - Components in `app/components/hub/` - React-heavy frontend with real-time features 3. **Storefronts (Public-Facing Sites)** - Public websites for creators (e.g., `creator.podia.com` or custom domains) - Primarily React-based rendering - Controllers in `app/controllers/storefront/` - Heavily cached for performance 4. **Admin Dashboard** - Internal tools for the Podia team - Controllers in `app/controllers/admin/` (60+ controllers) - No test coverage by convention ### Architectural Patterns **Service Objects** - **Interactors** (`app/interactors/`): Complex business logic using interactor-rails gem - Pattern: Include `Interactor`, define `call` method with `context` for input/output - Example: `Enrollments::Create`, `Campaign::Entry::Process` **Associated Objects** - Collaborator POROs using active_record-associated_object gem - Namespaced within ActiveRecord models for focused domain logic - Example: `Purchase::Processor`, `Purchase::Accountant` **Decorators** (`app/decorators/`) - Draper pattern for presentation logic - Keeps view concerns out of models **ViewComponents** (`app/components/`) - Reusable UI components with Lookbook previews - Modern component-based architecture replacing legacy HAML views **Model Concerns** (`app/models/concerns/`) - 64+ mixins for cross-cutting concerns - Examples: `Offering`, `Featurable`, `Integratable` ## Key Components ### Backend Components **Authentication & Authorization** - Rails `has_secure_password` for basic auth - OAuth2 via Doorkeeper with OpenID Connect - Separate Admin and User models - Feature flags via Flipper for granular access control **Multi-Tenancy** - Core concept: Everything scoped by `site_id` - Current tenant via `Current.site` - Hub context scopes to `Account` instead of `Site` - Critical security requirement: Always scope queries to prevent data leaks **Background Jobs** - Sidekiq Pro/Enterprise with multiple specialized queues - Base class: `ApplicationJob` - Periodic jobs in `app/jobs/periodic/` - Monitoring via Cronitor **State Machines** - Workflow gem for complex state management - `workflow_state` column stores current state - Examples: `Cart`, `Newsletter`, `AudienceImport` **Event System** - wisper-activerecord for pub/sub architecture - Subscribers in `app/subscribers/` - Decouples business logic from side effects - Used for: campaign enrollment, analytics, integrations **Cloning System** (`app/cloners/`) - Uses clowne gem for product/course duplication - Supports deep copying of complex product structures **Query Objects** (`app/queries/`) - Encapsulate complex SQL queries - Keep ActiveRecord models clean ### Frontend Components **JavaScript Stack** - React 18.3.1 for modern UI components - esbuild for fast bundling (via jsbundling-rails) - Stimulus 3.2.2 for progressive enhancement - StimulusReflex 3.5.0-pre9 (legacy, being phased out) **CSS & Styling** - SCSS compiled via Sass (cssbundling-rails) - Bootstrap 4.6.2 foundation - styled-components for React styling - Custom design system in `app/assets/ui/` **Rich Text Editing** - TipTap 2.11.5 (Prosemirror-based editor) - Replaces legacy Trix editor - Custom extensions for mentions, links, embeds **Real-Time Features** - Hotwire/Turbo for server-driven UI updates - ActionCable WebSocket channels - Chat/messaging infrastructure **Component Library** - ViewComponent for server-side components - Lookbook for component previews/documentation - Located in `/view_component/previews` during development ### Data & Storage **Database** - PostgreSQL 17.5 - pg_search for full-text search - Complex schema with 244+ models - Active Record migrations with strong_migrations gem **File Storage** - AWS S3 via Active Storage - Cloudflare CDN for delivery - ruby-vips for image processing - Direct upload support - tus-js-client for resumable uploads **Caching** - Redis 7.2.3 - Used for: Sidekiq, Flipper, Rails cache - Development caching enabled for StimulusReflex ### Integrations **Payment Processing** - Stripe 5.55.0 (primary) - PayPal integration - Stripe CLI for local webhook testing **Email Services** - Postmark Rails for transactional email - Sparkpost integration - letter_opener for development - Newsletter delivery system **Third-Party Integrations** - Zapier webhooks - Discord integration - Zoom API for webinars - Multiple email marketing platforms - Rewardful for affiliates ## Technologies Used ### Core Stack **Backend** - Ruby 3.4.7 - Rails 8.0 (with bootboot for dual-boot support to Rails Next) - PostgreSQL 17.5 - Redis 7.2.3 - Sidekiq Pro/Enterprise **Frontend** - Node.js 22.11.0 - React 18.3.1 - esbuild 0.15.9 - Sass 1.77.4 - Stimulus 3.2.2 - Turbo 8.0.16 ### Key Ruby Gems **Business Logic** - interactor-rails (service objects) - active_record-associated_object (domain objects) - workflow (state machines) - wisper-activerecord (pub/sub events) **Views & Presentation** - view_component (4.1.1) - draper (decorators) - haml (legacy, being phased out) - lookbook (component previews) **Data & Persistence** - pg_search (PostgreSQL full-text search) - audited (audit trails) - kaminari (pagination) - paranoia (soft deletes likely) **Authentication & Security** - doorkeeper (OAuth2) - doorkeeper-openid_connect - bcrypt (via has_secure_password) **External Services** - stripe (5.55.0) - aws-sdk-s3 - postmark-rails - sidekiq (Pro/Enterprise features) **Testing & Quality** - rspec-rails - factory_bot_rails - capybara - capybara-playwright-driver - webmock - vcr - shoulda-matchers - parallel_tests with knapsack_pro **Development Tools** - standard (Ruby linting) - bullet (N+1 query detection) - brakeman (security scanning) - chamber (configuration management) - flipper (feature flags) ### JavaScript Packages **Core Libraries** - react & react-dom (18.3.1) - @hotwired/stimulus (3.2.2) - @hotwired/turbo-rails (8.0.16) - stimulus_reflex (3.5.0-pre9, legacy) **Rich Text & Content** - @tiptap/\* (2.11.5 - suite of editor extensions) - highlight.js (11.11.1 for code highlighting) - prosemirror-codemark (0.4.2) **UI Components** - styled-components (6.1.15) - tippy.js (6.3.7 for tooltips) - @tippyjs/react (4.2.6) - react-color (2.19.3 for color pickers) - flatpickr (4.6.13 for date pickers) **Data & State** - lodash-es (4.17.21) - immutability-helper (3.1.1) - moment (2.29.4) & luxon (3.5.0) for dates **Testing** - jest (29.7.0) - @testing-library/react (16.2.0) - @testing-library/jest-dom (6.6.3) - playwright (1.56.1) ## Data Flow ### Request Lifecycle 1. **Entry Point** - Request hits Rails router - Subdomain routing determines context (CMS, Hub, Storefront, Admin) - Chamber loads environment-specific configuration 2. **Authentication & Tenancy** - User/Admin authentication via session or OAuth - `Current.site` set based on subdomain or custom domain - Flipper checks feature flags for user/site 3. **Controller Processing** - Controllers delegate to Interactors for complex business logic - Query objects handle complex data retrieval - Models use Associated Objects for domain logic 4. **View Rendering** - ViewComponents for reusable UI elements - React components for interactive features - Decorators add presentation logic - Turbo Streams for real-time updates 5. **Background Processing** - Complex operations enqueued to Sidekiq - Wisper events trigger side effects (emails, analytics, webhooks) - Jobs process asynchronously with retry logic ### Data Flow Examples **Student Enrollment Flow** 1. Customer completes checkout (Stripe webhook) 2. `Purchase::Processor` creates purchase record 3. `Enrollments::Create` interactor creates enrollment 4. Wisper broadcasts enrollment event 5. Subscribers trigger: welcome email, analytics, campaign entry 6. Background job processes course access provisioning **Campaign Automation** 1. Enrollment event triggers campaign evaluation 2. `Campaign::Entry::Process` checks entry conditions 3. If matched, creates campaign subscription 4. Drip sequence scheduler queues emails 5. Background jobs deliver emails via Postmark 6. Link clicks tracked, campaign exit conditions evaluated **Content Publishing** 1. Creator edits course in CMS 2. TipTap editor saves rich content as JSON 3. Maintenance task migrates legacy HTML to TipTap format 4. ViewComponents render for storefront 5. React components handle interactive elements 6. Cloudflare CDN caches public pages ## Team and Ownership ### Core Development Team (by Commit Count, Last year) 1. **Jason Charnes** - 2,528 commits (23.4%) - Top contributor, likely senior/lead developer - Broad contributions across the stack 2. **Mario Zugaj** - 2,369 commits (21.9%) - Nearly equal contribution to Jason - Co-lead role with high deployment responsibility - Tied for most production deploys in recent history 3. **Harry Llewelyn** - 1,200 commits (11.1%) - Significant contributor - Substantial feature development 4. **Diogo Beda** - 1,114 commits (10.3%) - Major contributor to core features - Regular production deployments 5. **Kyle Fox** - 925 commits (8.6%) - Regular contributor - Consistent development velocity and deployment cadence 6. **Pedro Gaspar** - 759 commits (7.0%) - Active team member - Handles production deployments 7. **Stephanie Wiggins** - 577 commits (5.3%) - Regular contributions - Component architecture and deployment work 8. **Drew Bragg** - 332 commits (3.1%) - Squashes commits (understates contribution) - Tied with Mario for most production deploys - Deployment champion and infrastructure focus 9. **Jamie Lawrence** - 291 commits (2.7%) - Consistent presence 10. **Andrew Mason** - 278 commits (2.6%) - Squashes commits (understates contribution) - Infrastructure and AI tooling development ### Team Characteristics - **Small, Expert Team**: Self-described as "a small fully remote team, who are experts in Ruby and Rails" - **Collaborative**: 22% of commits are merges, indicating strong PR-based workflow - **Distributed**: Fully remote with contributors across time zones, deploys happening 24/7 - **Automation-Friendly**: depfu[bot] with 219 commits handling dependency updates - **Active Code Review**: Review apps and PR process are core to workflow - **Deployment-Confident**: Multiple team members deploy to production regularly, averaging 5 deploys/day - **Workflow-Flexible**: Some developers squash commits, others preserve history—both accepted ### Development Culture - **Quality-Focused**: Extensive test coverage (RSpec, Jest, Playwright) - **Security-Conscious**: Brakeman scanning, careful multi-tenancy implementation - **Performance-Aware**: Bullet gem for N+1 detection, JudoScale for autoscaling - **Gradual Evolution**: "Respects existing patterns; gradual evolution over aggressive refactoring" - **Modern Practices**: Feature flags, continuous deployment, automated review apps ## Infrastructure & Deployment ### Hosting & Deployment **Platform**: Heroku - **Production**: podia.com (currently at v11,165) - **Staging**: podia.tech (currently at v17,636, auto-deploys from `main` branch) - **Review Apps**: pr-name.review.podia.tech (auto-provisioned per PR) **Deployment Statistics** - **11,165 production releases** since September 2014 - **Average 2.7 deploys per day** over 11 years - **Recent velocity: ~5 deploys per day** (November 2025) - **17,636 staging releases**—60% more than production - Staging-to-production promotion often within minutes - No deployment freezes—ships continuously including weekends **Deployment Pipeline** 1. Developer pushes to feature branch 2. Creates PR → Review app auto-provisioned 3. Merges to `main` → CI tests run 4. Tests pass → Auto-deploy to staging 5. Manual promotion from staging to production (often same-day) 6. Migrations run automatically during release phase **Deployment Culture** - Multiple team members deploy regularly (Drew, Mario, Jason, Kyle, Pedro, Stephanie, Diogo) - Deploys happen around the clock across time zones - High confidence in automated testing and rollback procedures - Feature flags enable safe deployment of incomplete features **Git Workflow & Pull Requests** - Main branch: `main` - Feature branches off `main` - Pull request → review → merge - Small changes can go directly to `main` - PR tagging system for organization: - `[🏠], [Hub]` - Hub features - `[Chat]` - Chat/messaging features - `[PODIA-####]` - Linear ticket references - `[AI]`, `[security]`, `[Herb]` - Various development feature areas - Multi-phase rollout pattern: Phase 1, Phase 2, Phase 3 for risky changes - Fast turnaround: Many PRs merged same-day or within hours - Automated workflows trigger on every PR: - CI tests (RSpec, Jest, Playwright system tests) - CodeQL security scanning - Claude AI code review (on-demand via PR comments) - Code quality checks (Standard, ESLint) ### Monitoring & Operations **Application Monitoring** - AppSignal (APM and error tracking) - JudoScale (autoscaling) - Cronitor (scheduled job monitoring) **Development Tools** - Flipper Cloud (feature flag management) - Heroku Pipelines (deployment workflow) - GitHub Actions - CodeQL (security scanning) - Claude AI integration (on-demand PR reviews and log investigation) - Danger (automated code review) - depfu bot (automated dependency updates) **Local Development** - overmind/foreman for process management - Procfile.dev for custom configurations - SSL support on port 3001 (via local certificates) - `*.local.podia.tech` subdomains for multi-tenancy testing ### Configuration Management **Chamber** (Secrets Management) - Encrypted YAML files in `config/settings/` - Separate configs per environment and hostname - Keys prefixed with `_secure_` are encrypted - Supports namespaces beyond Rails environments ### Database Management **PostgreSQL** - Production database cloned to staging regularly - Review apps can use staging DB or dedicated instance - Migrations use strong_migrations gem to prevent downtime - Full-text search via pg_search **Redis** - Shared between Sidekiq and Flipper - Local development uses default database (db 0) - Potential for job cross-contamination in local multi-app setups ## Recent Evolution & Focus Areas ### Major Themes (Last 6 Months) 1. **site_id Denormalization** - Adding `site_id` column to multiple tables - Performance optimization to reduce JOIN queries - Multi-phase rollout: add column → backfill → add constraint → remove optional - Examples: quiz_quizzes, pages_links, page_testimonials, affiliate_product_commissions 2. **Hub Development** - Significant strategic focus with dedicated team effort - New community/social features transforming the platform - Hub-specific controllers, components, and decorators - Full messaging platform with chat - Typing indicators, unread counts, conversation management - Topic/post features with responsive design - Notification system and real-time updates - Feature flag gated rollout with careful phasing 3. **Legacy Migration** - HAML → ViewComponent transition - Legacy HTML → TipTap JSON migration - StimulusReflex → Turbo migration - Maintenance tasks for data migrations 4. **Campaign Improvements** - Enhanced entrance/exit tracking - Audit logging for enrollment state changes - Subscription table improvements in admin - Better analytics and reporting 5. **Feature Flag Infrastructure** - Extensive use of Flipper for gradual rollouts - Site-specific and user-specific feature enabling - A/B testing capabilities - Hub realm separation ### Most Frequently Changed Files These files see the most activity, indicating core areas of development: - `Gemfile.lock` (248 changes) - Active dependency management - `spec/models/course_spec.rb` (88 changes) - Core product model - `spec/models/cart_spec.rb` (88 changes) - Checkout functionality - `spec/models/product_spec.rb` (80 changes) - Product variants - `spec/models/student_spec.rb` (68 changes) - Student lifecycle - `spec/models/enrollment_spec.rb` (68 changes) - Enrollment logic Test files dominate the most-changed list, indicating strong TDD culture. ## Technical Debt & Evolution ### Deprecated Technologies The team is actively phasing out: - **StimulusReflex** - Moving to Turbo for real-time features - **HAML** - Transitioning to ViewComponents and React - Legacy HTML in rich content - Migrating to TipTap JSON ### Current Challenges **Known Gotchas** (per AGENTS.md): 1. **Async Operations** - Most operations are async via Sidekiq 2. **Feature Flags** - Features may be enabled only for specific users/sites 3. **Migrations** - strong_migrations prevents downtime-inducing changes 4. **Audit Trail** - Changes logged via audited gem 5. **Multi-tenancy** - Unscoped queries can leak data across tenants ### Quality Tools **Active in Development**: - `isolator` - Detects non-atomic database transactions - `bullet` - Kills N+1 queries and unused eager loading - `danger` - Automates code review chores - `rack_mini_profiler` - Profiling for performance analysis - `testprof` - Ruby test profiling toolbox - `stackprof` - Sampling call-stack profiler - `brakeman` - Static security analysis ## Future Direction Based on recent activity and architecture, the repository is focused on: 1. **Hub Maturation** - Completing the community platform as a core offering 2. **Performance Optimization** - site_id denormalization project reducing database load 3. **Modern Frontend** - Completing transition to React + ViewComponent architecture 4. **Scalability** - Background job optimization and improved caching 5. **Feature Velocity** - Feature flag infrastructure enables rapid experimentation 6. **Deployment Acceleration** - Recent increase from 2.7 to 5 deploys/day suggests even faster iteration cycles The codebase shows hallmarks of a mature SaaS application: strong testing culture, confident deployment practices (11,165+ production releases), gradual modernization, and a team that prioritizes shipping features while managing technical debt strategically. The accelerating deployment velocity (nearly doubling from historical average) indicates a team that's becoming even more confident in their ability to ship safely and quickly.