How daniel-vizcarra/film_sonar works
Project Type & Purpose
• Full-stack, monolithic Ruby on Rails 8 web application.
• Purpose: Personalized movie suggestions platform with browsable catalog, watchlist, favorites, and PWA support.
• Key tech: Rails (MVC), Hotwire (Turbo + Stimulus), Importmaps, Sass, PostgreSQL, Docker Compose, Puma.
Main Components
a. Clients
• Web browser (desktop/mobile)
• PWA shell (service worker + manifest.json)
b. Web & App Layer
• Puma web server (serves HTTP/TCP)
• Rails application (MVC):
– Controllers (app/controllers)
– Views (ERB, Hotwire templates in app/views)
– Models (ActiveRecord in app/models)
– Jobs (ActiveJob in app/jobs)
• Asset pipeline: Propshaft + dartsass-rails for CSS/SCSS, Importmaps for JS
c. Data Layer
• PostgreSQL (config/database.yml)
• db/migrate & schema.rb
d. DevOps & Infrastructure
• Docker + Docker Compose (docker-compose.yml, Dockerfile)
• Foreman for local process management (Procfile.dev)
• .kamal hooks for deploy automation
e. (Optional) External Services
• Email (ActionMailer)
• WebSockets / ActionCable (config/cable.yml)
Relationships & Data Flows
1. User → Browser/PWA
– Loads HTML/JS/CSS from Rails via HTTP(S)
– Interacts through Turbo (XHR/fetch) & Stimulus controllers
2. Browser → Puma/Rails
– HTTP GET/POST → Rails router (config/routes.rb) → Controllers
– Controllers invoke Models → PostgreSQL
– Controllers render Views (ERB + Hotwire partials) or JSON/Turbo Streams
3. Rails → PostgreSQL
– ActiveRecord queries over TCP
– Migrations build schema, seeds populate initial data
4. Background Jobs
– Enqueued by controllers or models → ActiveJob adapter (e.g., inline, Sidekiq)
5. PWA
– service-worker.js intercepts fetch events for offline mode
Architectural Patterns & Design Principles
• MVC (Model-View-Controller)
• Hotwire (Turbo Frames/Streams) for partial page updates
• Stimulus for small, focused JS controllers
• Importmaps delivering JS modules without a bundler
• Propshaft + dartsass for CSS pipeline
• Containerized development with Docker Compose
Diagramming Essentials Checklist
• Version numbers for critical components (Rails 8, Ruby 3.3.7, Postgres 15)