How jcraigk/phishin works
Project Type and Purpose
• This is a full‐stack open‐source application (“Phish.in”) that provides:
• A React‐based web frontend (SPA, built with Shakapacker/Webpack) for browsing and playing live Phish recordings.
• A JSON API (two versions: v1 implemented via Rails controllers, v2 via Grape) for programmatic access.
• A Ruby on Rails backend (models, controllers, Service objects) using PostgreSQL to store metadata, Sidekiq for background jobs, and ActiveStorage/public folders to serve audio‐related assets.
• Static assets (MP3s, waveform images, album art) are served by the web server and cached on CloudFlare CDN.
• Integration with Phish.net for content import and optional Discord bot integration.
File Structure Analysis
• Top‐level:
• app/api/api_v2 … Grape endpoints, entities, helpers for API v2
• app/controllers/api/v1 … Rails controllers for API v1
• app/javascript … React components, pages, routes, stylesheets
• app/models, app/services, app/jobs, app/mailers … Rails MVC plus Service & Job layers
• config/webpack, babel.config.js, package.json … client‐side build config
• config/routes.rb, puma/sidekiq configs, Dockerfile, docker-compose.yml, Makefile
• Architectural patterns:
• Monolithic Rails app subdivided into MVC + Service Objects
• API split: Grape for API v2 vs Rails controllers for API v1
• React SSR and CSR via React‐on‐Rails (server‐bundle.js)
• Background processing with Sidekiq
• Asset pipeline separated: public storage + CDN
• Deployment/infra:
• Docker + Docker Compose
• CDN (CloudFlare) in front of Rails web server
• Postgres container
• Sidekiq container
README Insights
• Confirms Rails + Grape + Postgres backend, React frontend, CloudFlare CDN for MP3s & images.
• Mentions Swagger docs for API v2.
• Developer setup: Docker, environment variables, content import CLI.
a. Main Components
1. Web Client (Browser/SPA)
2. Rails Web Server (Puma)
• React‐on‐Rails SSR & static asset server
• Rails MVC/API v1
• Grape API v2
• Sidekiq background worker
• Service Objects & Jobs
3. PostgreSQL Database
4. Storage Layer
• Local filesystem or S3 (via ActiveStorage) and public/placeholder assets
• CloudFlare CDN
5. External Services
• Phish.net API (import)
• Optional: Discord Bot
• Sentry (error logging)
b. Relationships & Data Flows
• Browser ↔ Rails Web Server: HTTP(S) GET/POST for pages & JSON API calls
• Rails Server → Postgres: SQL queries (ActiveRecord)
• Rails Server → Sidekiq: enqueue jobs
• Sidekiq Worker → Rails Services → DB / filesystem
• Rails Server → Storage / public/ → CDN → Browser (static assets)
• Rails Import CLI → Phish.net API → Rails Services → DB + storage
c. Architectural Patterns
• MVC for core web UI & API v1
• Service-object layer for business logic (e.g., search_service, importers)
• Grape micro-framework for API v2 endpoints & entity serializers
• React SPA with SSR fallback via react_on_rails
• Background processing via Sidekiq
• Dockerized orchestration
d. Key Technologies
• Ruby on Rails, Grape, PostgreSQL
• React, Shakapacker/Webpack, Babel
• Sidekiq, Redis (for jobs)
• Docker, Docker Compose
• CloudFlare CDN, Sentry
• Phish.net API