# dcowett/jubilant-engine architecture

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

- Interactive diagram: https://gitdiagram.com/dcowett/jubilant-engine
- Repository: https://github.com/dcowett/jubilant-engine

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Ruby on Rails web application that implements a simple microblog: users sign up, log in, post “microposts,” follow/unfollow other users, and receive email notifications (activation, password reset).
- It uses MVC (Model-View-Controller), the Rails asset pipeline (SCSS, Importmap, Stimulus), Active Storage for image uploads, Action Mailer for emails, and Active Job/Action Cable hooks for background jobs and real-time channels.

##### Main high-level components
a. Client (Web Browser)
– Renders HTML/ERB views and CSS (application.scss, custom.scss)
– Runs Stimulus controllers and custom JavaScript (app/javascript)
b. Rails Application Server
– Rack stack + Puma web server (Procfile, puma.rb)
– Rails Router (config/routes.rb) dispatching to Controllers
– Controllers (app/controllers/*) implementing RESTful endpoints
– Views (app/views/*.erb) generating HTML responses
– Models (app/models/*.rb) with ActiveRecord ORM, validations, associations
– Mailers (app/mailers/*) sending account‐activation & password‐reset emails
– Jobs (app/jobs/*) for background processing (Active Job)
– Channels (app/channels/*) for WebSocket connections (Action Cable)
– Active Storage (config/storage.yml + service adapters) for file uploads
c. Data Stores
– Relational Database (SQLite in development, PostgreSQL in production)
– File storage (local disk in dev, AWS S3 in prod via Active Storage)
– (Optional) Redis for Action Cable or background adapter in production
d. External Services
– SMTP service (e.g. SendGrid) for outbound mail
– AWS S3 for image storage (production)
– Heroku platform for deployment (web & worker dynos)

##### Relationships and data flows
– Browser → HTTP(S) request → Puma/Rack middleware → Rails Router → Controller action
– Controller ↔ Model (ActiveRecord) ↔ Database
– Controller → View → HTML → Browser
– Browser ↔ WebSocket → Action Cable server → Channel classes
– Controller/Mailer/Job → SMTP → External mail service → User email inbox
– Controller/Job → Active Storage adapter → AWS S3 (prod)
– Controller enqueues background jobs → Active Job adapter → (Redis/DB) → Worker dyno

##### Architectural patterns & design principles
– MVC: clear separation of concerns (Models, Controllers, Views)
– RESTful resource routing for Users, Sessions, Microposts, Relationships, PasswordResets, AccountActivations
– Asset pipeline + Importmap + Stimulus for progressive enhancement
– Layered architecture: Web layer, Application layer, Data layer
– Use of background jobs and Action Cable hooks for scalability and responsiveness

##### Final checklist
- MVC boundaries, the asset‐pipeline/client boundary, and the external service boundary

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (Web Browser)"
        Browser["Browser\n(HTML, CSS, JS)"]:::client
        Assets["Assets\napp/assets/\napp/javascript/"]:::client
    end

    click Assets "https://github.com/dcowett/jubilant-engine/blob/main/app/assets/stylesheets/application.scss"
    click Assets "https://github.com/dcowett/jubilant-engine/blob/main/app/assets/stylesheets/custom.scss"
    click Assets "https://github.com/dcowett/jubilant-engine/tree/main/app/assets/images/"
    click Assets "https://github.com/dcowett/jubilant-engine/blob/main/app/javascript/application.js"
    click Assets "https://github.com/dcowett/jubilant-engine/tree/main/app/javascript/controllers/"
    click Assets "https://github.com/dcowett/jubilant-engine/tree/main/app/javascript/custom/"

    Browser -->|"HTTP Requests"| Puma

    subgraph "Rails Application"
        direction TB

        subgraph "Web & App Server"
            direction TB
            Puma["Puma/Rack"]:::server
            Router["Router\nconfig/routes.rb"]:::server
        end

        Puma -->|"Dispatch"| Router

        subgraph MVC
            direction TB
            Controllers["Controllers\napp/controllers/"]:::code
            Views["Views\napp/views/"]:::code
            Models["Models\napp/models/"]:::code
        end

        Router --> Controllers
        Controllers --> Models
        Controllers --> Views
        Models -->|"CRUD"| DB
        Views --> Browser

        click Router "https://github.com/dcowett/jubilant-engine/blob/main/config/routes.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/application_controller.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/users_controller.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/sessions_controller.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/microposts_controller.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/relationships_controller.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/password_resets_controller.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/account_activations_controller.rb"
        click Controllers "https://github.com/dcowett/jubilant-engine/blob/main/app/controllers/static_pages_controller.rb"
        click Views "https://github.com/dcowett/jubilant-engine/blob/main/app/views/layouts/application.html.erb"
        click Views "https://github.com/dcowett/jubilant-engine/tree/main/app/views/users/"
        click Views "https://github.com/dcowett/jubilant-engine/blob/main/app/views/sessions/new.html.erb"
        click Views "https://github.com/dcowett/jubilant-engine/blob/main/app/views/microposts/_micropost.html.erb"
        click Views "https://github.com/dcowett/jubilant-engine/blob/main/app/views/shared/_feed.html.erb"
        click Views "https://github.com/dcowett/jubilant-engine/blob/main/app/views/shared/_micropost_form.html.erb"
        click Views "https://github.com/dcowett/jubilant-engine/tree/main/app/views/password_resets/"
        click Views "https://github.com/dcowett/jubilant-engine/tree/main/app/views/static_pages/"
        click Views "https://github.com/dcowett/jubilant-engine/tree/main/app/views/user_mailer/"
        click Models "https://github.com/dcowett/jubilant-engine/blob/main/app/models/user.rb"
        click Models "https://github.com/dcowett/jubilant-engine/blob/main/app/models/micropost.rb"
        click Models "https://github.com/dcowett/jubilant-engine/blob/main/app/models/relationship.rb"
        click Models "https://github.com/dcowett/jubilant-engine/blob/main/app/models/application_record.rb"

        subgraph "Mailers"
            Mailers["Mailers\napp/mailers/"]:::code
        end
        Controllers --> Mailers
        Mailers -->|"Email"| SMTP
        click Mailers "https://github.com/dcowett/jubilant-engine/blob/main/app/mailers/user_mailer.rb"
        click Mailers "https://github.com/dcowett/jubilant-engine/blob/main/app/mailers/application_mailer.rb"

        subgraph "Background Jobs"
            Jobs["Jobs\napp/jobs/"]:::code
        end
        Controllers -->|"Enqueue"| Jobs
        click Jobs "https://github.com/dcowett/jubilant-engine/blob/main/app/jobs/application_job.rb"

        subgraph "Action Cable"
            Channels["Channels\napp/channels/"]:::code
        end
        Browser -->|"WebSocket"| Channels
        Channels --> Controllers
        click Channels "https://github.com/dcowett/jubilant-engine/blob/main/app/channels/application_cable/connection.rb"
        click Channels "https://github.com/dcowett/jubilant-engine/blob/main/app/channels/application_cable/channel.rb"

        subgraph "Active Storage"
            AS["Active Storage\nconfig/storage.yml"]:::data
        end
        Controllers -->|"Upload"| AS
        click AS "https://github.com/dcowett/jubilant-engine/blob/main/config/storage.yml"
    end

    subgraph "Data Stores"
        DB["Relational DB\nSQLite/PostgreSQL"]:::data
        S3["File Storage\nAWS S3"]:::external
        Redis["Redis (optional)"]:::data
    end

    DB --> Workers
    Redis --> Workers

    subgraph "External Services"
        SMTP["SMTP Service\nSendGrid"]:::external
        Heroku["Heroku\nweb & worker dynos"]:::external
    end

    Jobs --> Workers
    Workers["Worker Dyno"]:::server
    Jobs --> Workers
    Workers --> Redis
    Workers --> AS

    Heroku --> Puma
    Heroku --> Workers

    click DB "https://github.com/dcowett/jubilant-engine/blob/main/config/database.yml"
    click DB "https://github.com/dcowett/jubilant-engine/blob/main/db/schema.rb"
    subgraph "Migrations"
        Migs["db/migrate/"]:::data
    end
    click Migs "https://github.com/dcowett/jubilant-engine/tree/main/db/migrate/"

    classDef client fill:#D6EFFF,stroke:#0288D1
    classDef server fill:#E8F5E9,stroke:#43A047
    classDef code fill:#FFF3E0,stroke:#FB8C00
    classDef data fill:#FFE0B2,stroke:#FB8C00
    classDef external fill:#E1BEE7,stroke:#8E24AA
```
