# daniel-vizcarra/film_sonar architecture

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

- Interactive diagram: https://gitdiagram.com/daniel-vizcarra/film_sonar
- Repository: https://github.com/daniel-vizcarra/film_sonar

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        User["User"]:::external
        Browser["Web Browser (Desktop/Mobile)"]:::frontend
        subgraph "PWA Shell" 
            direction TB
            SW["service-worker.js"]:::frontend
            Manifest["manifest.json"]:::frontend
        end
    end

    %% Web Server
    Puma["Puma Web Server"]:::backend

    %% Rails Application Layer
    subgraph "Rails Application" 
        direction TB
        Routes["config/routes.rb"]:::backend
        Controllers["Controllers (app/controllers/*.rb, admin/, movies/)"]:::backend
        Views["Views (app/views/**/*.html.erb)"]:::frontend
        Models["Models (app/models/*.rb, concerns/)"]:::backend
        Jobs["Background Jobs (app/jobs/application_job.rb)"]:::backend
        Mailers["Mailers (app/mailers/application_mailer.rb)"]:::backend
        subgraph "Asset Pipeline" 
            direction TB
            Styles["CSS/SCSS (app/assets/stylesheets/)"]:::frontend
            Images["Images (app/assets/images/)"]:::frontend
            JS["JS Importmaps (config/importmap.rb, app/javascript/)"]:::frontend
        end
        ActionCableExt["ActionCable (config/cable.yml)"]:::external
        EmailExt["Email Service"]:::external
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        Postgres["PostgreSQL"]:::data
        DBConfig["config/database.yml"]:::data
        Migrations["db/migrate/ & db/schema.rb"]:::data
        Seeds["db/seeds.rb & CSV import"]:::data
    end

    %% DevOps & Infra
    subgraph "DevOps & Infrastructure" 
        direction TB
        Docker["Docker & Compose (Dockerfile, docker-compose.yml)"]:::infra
        Foreman["Foreman (Procfile.dev)"]:::infra
        Kamal[".kamal Hooks"]:::infra
    end

    %% Connections - Clients to Server
    User -->|visits| Browser
    Browser -->|HTTP/HTTPS| Puma
    SW -.->|fetch intercept| Browser

    %% PWA click events
    click SW "https://github.com/daniel-vizcarra/film_sonar/blob/master/app/views/pwa/service-worker.js"
    click Manifest "https://github.com/daniel-vizcarra/film_sonar/blob/master/app/views/pwa/manifest.json.erb"

    %% Server flow
    Puma -->|HTTP Request| Routes
    Routes -->|dispatch| Controllers
    Controllers -->|render| Views
    Controllers -->|invoke| Models
    Models -->|SQL Queries| Postgres
    Controllers -->|enqueue| Jobs
    Controllers -->|send| Mailers
    Views -->|HTML/JS/CSS| Browser
    Controllers -.->|WebSocket| ActionCableExt
    Controllers -.->|SMTP| EmailExt

    %% Assets
    Browser -->|requests assets| JS
    Browser -->|requests assets| Styles
    Browser -->|requests assets| Images

    %% Data Layer flow
    DBConfig --> Postgres
    Migrations --> Postgres
    Seeds --> Postgres

    %% DevOps connections
    Docker --> Puma
    Docker --> Postgres
    Foreman --> Puma
    Kamal --> Docker

    %% Click Events - Server
    click Puma "https://github.com/daniel-vizcarra/film_sonar/blob/master/config/puma.rb"
    click Routes "https://github.com/daniel-vizcarra/film_sonar/blob/master/config/routes.rb"
    click Controllers "https://github.com/daniel-vizcarra/film_sonar/tree/master/app/controllers/"
    click Views "https://github.com/daniel-vizcarra/film_sonar/tree/master/app/views/"
    click Models "https://github.com/daniel-vizcarra/film_sonar/tree/master/app/models/"
    click Jobs "https://github.com/daniel-vizcarra/film_sonar/blob/master/app/jobs/application_job.rb"
    click Mailers "https://github.com/daniel-vizcarra/film_sonar/blob/master/app/mailers/application_mailer.rb"
    click Styles "https://github.com/daniel-vizcarra/film_sonar/tree/master/app/assets/stylesheets/"
    click Images "https://github.com/daniel-vizcarra/film_sonar/tree/master/app/assets/images/"
    click JS "https://github.com/daniel-vizcarra/film_sonar/blob/master/config/importmap.rb"
    click JS "https://github.com/daniel-vizcarra/film_sonar/blob/master/app/javascript/application.js"
    click JS "https://github.com/daniel-vizcarra/film_sonar/tree/master/app/javascript/controllers/"
    click DBConfig "https://github.com/daniel-vizcarra/film_sonar/blob/master/config/database.yml"
    click Migrations "https://github.com/daniel-vizcarra/film_sonar/tree/master/db/migrate/"
    click Migrations "https://github.com/daniel-vizcarra/film_sonar/blob/master/db/schema.rb"
    click Seeds "https://github.com/daniel-vizcarra/film_sonar/blob/master/db/seeds.rb"
    click Seeds "https://github.com/daniel-vizcarra/film_sonar/blob/master/lib/data/movies.csv"
    click Seeds "https://github.com/daniel-vizcarra/film_sonar/blob/master/lib/tasks/import_movies.rake"
    click Docker "https://github.com/daniel-vizcarra/film_sonar/tree/master/Dockerfile"
    click Docker "https://github.com/daniel-vizcarra/film_sonar/blob/master/docker-compose.yml"
    click Foreman "https://github.com/daniel-vizcarra/film_sonar/blob/master/Procfile.dev"
    click Kamal "https://github.com/daniel-vizcarra/film_sonar/tree/master/.kamal/hooks/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0F0D0,stroke:#333,stroke-width:1px
    classDef data fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
