# jcraigk/phishin architecture

> Architecture diagram of the GitHub repository jcraigk/phishin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jcraigk/phishin
- Repository: https://github.com/jcraigk/phishin

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        ReactSPA["React SPA"]:::frontend
        BabelConfig["babel.config.js"]:::infra
        WebpackConfig["config/webpack/"]:::infra
        FrontendPack["app/javascript/packs/application.js"]:::frontend
        SSRBundle["app/javascript/packs/server-bundle.js"]:::frontend
        ReactOnRailsInit["react_on_rails initializer"]:::backend
        ServerWebpackConfig["config/webpack/serverWebpackConfig.js"]:::infra
        ApiDocs["API Docs Page"]:::frontend
        DiscordBotUI["Discord Bot UI"]:::frontend
    end

    %% Rails Monolith
    subgraph "Rails Monolith" 
        direction TB
        PumaRails["Puma/Rails Server"]:::backend

        subgraph "MVC & API v1"
            direction TB
            Controllers["app/controllers/api/v1/ (API v1)"]:::backend
            Models["app/models/"]:::backend
            Views["app/views/"]:::backend
            Routes["config/routes.rb"]:::infra
        end

        subgraph "Grape API v2"
            direction TB
            APIv2["app/api/api_v2/"]:::backend
        end

        subgraph "Services & Jobs"
            direction TB
            Services["app/services/"]:::backend
            Jobs["app/jobs/"]:::backend
            SidekiqInit["Sidekiq initializer"]:::infra
            SidekiqYml["config/sidekiq.yml"]:::infra
        end
    end

    %% Data Stores
    subgraph "Data Layer"
        direction TB
        Postgres["PostgreSQL DB"]:::datastore
        StorageConfig["config/storage.yml"]:::infra
        Placeholders["public/placeholders/"]:::infra
        Migrations["db/migrate/"]:::infra
        DBConfig["config/database.yml"]:::infra
        Schema["db/schema.rb"]:::infra
    end

    %% External & Infra
    subgraph "Infrastructure & External"
        direction TB
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        MakefileNode["Makefile"]:::infra
        ProcfileNode["Procfile"]:::infra
        SentryInit["Sentry initializer"]:::infra
        PnetRake["lib/tasks/pnet.rake"]:::external
        ShowsRake["lib/tasks/shows.rake"]:::external
        BinRails["bin/rails"]:::infra
        PhishNet["Phish.net API"]:::external
        DiscordBot["Discord Bot"]:::external
        CDN["CloudFlare CDN"]:::infra
    end

    %% Relationships
    ReactSPA -->|HTTP/HTTPS| PumaRails
    ReactSPA -->|fetch API| Controllers
    ReactSPA -->|SSR| SSRBundle
    PumaRails -->|ActiveRecord| Postgres
    PumaRails -->|enqueue jobs| Jobs
    Jobs -->|process| Services
    Services -->|read/write| Postgres
    Services -->|store assets| Placeholders
    PumaRails -->|serve assets| Placeholders
    Placeholders -->|cached by| CDN
    CDN -->|deliver| ReactSPA
    PumaRails -->|import CLI| PnetRake
    PnetRake -->|calls| Services
    Services -->|calls| PhishNet
    ReactSPA -->|UI| DiscordBot
    PumaRails -->|error logging| SentryInit

    %% Click Events
    click ReactSPA "https://github.com/jcraigk/phishin/tree/main/app/javascript/"
    click BabelConfig "https://github.com/jcraigk/phishin/blob/main/babel.config.js"
    click WebpackConfig "https://github.com/jcraigk/phishin/tree/main/config/webpack/"
    click FrontendPack "https://github.com/jcraigk/phishin/blob/main/app/javascript/packs/application.js"
    click SSRBundle "https://github.com/jcraigk/phishin/blob/main/app/javascript/packs/server-bundle.js"
    click ReactOnRailsInit "https://github.com/jcraigk/phishin/blob/main/config/initializers/react_on_rails.rb"
    click ServerWebpackConfig "https://github.com/jcraigk/phishin/blob/main/config/webpack/serverWebpackConfig.js"
    click ApiDocs "https://github.com/jcraigk/phishin/blob/main/app/javascript/components/pages/ApiDocs.jsx"
    click DiscordBotUI "https://github.com/jcraigk/phishin/blob/main/app/javascript/components/pages/DiscordButton.jsx"
    click Controllers "https://github.com/jcraigk/phishin/tree/main/app/controllers/api/v1/"
    click Routes "https://github.com/jcraigk/phishin/blob/main/config/routes.rb"
    click APIv2 "https://github.com/jcraigk/phishin/tree/main/app/api/api_v2/"
    click Services "https://github.com/jcraigk/phishin/tree/main/app/services/"
    click Jobs "https://github.com/jcraigk/phishin/tree/main/app/jobs/"
    click SidekiqInit "https://github.com/jcraigk/phishin/blob/main/config/initializers/sidekiq.rb"
    click SidekiqYml "https://github.com/jcraigk/phishin/blob/main/config/sidekiq.yml"
    click StorageConfig "https://github.com/jcraigk/phishin/blob/main/config/storage.yml"
    click Placeholders "https://github.com/jcraigk/phishin/tree/main/public/placeholders/"
    click Migrations "https://github.com/jcraigk/phishin/tree/main/db/migrate/"
    click DBConfig "https://github.com/jcraigk/phishin/blob/main/config/database.yml"
    click Schema "https://github.com/jcraigk/phishin/blob/main/db/schema.rb"
    click DockerfileNode "https://github.com/jcraigk/phishin/tree/main/Dockerfile"
    click Compose "https://github.com/jcraigk/phishin/blob/main/docker-compose.yml"
    click MakefileNode "https://github.com/jcraigk/phishin/tree/main/Makefile"
    click ProcfileNode "https://github.com/jcraigk/phishin/tree/main/Procfile"
    click SentryInit "https://github.com/jcraigk/phishin/blob/main/config/initializers/sentry.rb"
    click PnetRake "https://github.com/jcraigk/phishin/blob/main/lib/tasks/pnet.rake"
    click ShowsRake "https://github.com/jcraigk/phishin/blob/main/lib/tasks/shows.rake"
    click BinRails "https://github.com/jcraigk/phishin/tree/main/bin/rails"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E6FFEA,stroke:#1c912c,color:#1c912c;
    classDef datastore fill:#FFF5BA,stroke:#d4a017,color:#d4a017;
    classDef external fill:#FEEAEA,stroke:#d73232,color:#d73232;
    classDef infra fill:#F0F0F0,stroke:#888888,color:#333333;
```
