# railsapps/learn-rails architecture

> Architecture diagram of the GitHub repository railsapps/learn-rails, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/railsapps/learn-rails
- Repository: https://github.com/railsapps/learn-rails

## Overview

1. This is a Rails 5.1 “small business website” app: mostly server-rendered HTML, with two interactive business flows layered on top of static pages—mailing-list signup and contact-email submission.

2. The main request boundary is `config/routes.rb` into three areas: a visitor/home flow (`VisitorsController`), a contact form flow (`ContactsController`), and static content served through `high_voltage` for pages like About. The app is intentionally simple and does not expose an API.

3. The presentation layer is conventional Rails MVC views under `app/views`, with a shared layout in `app/views/layouts/application.html.erb`, navigation/message partials, and page-specific templates for the home/sign-up page, contact form, and About page. Styling is built with Foundation (`foundation-rails`) via the asset pipeline.

4. The home page signup flow centers on `Visitor` in `app/models/visitor.rb` and `VisitorsController`. The model exists primarily for validation; when a valid email is submitted, the app calls MailChimp through the `gibbon` gem using API credentials from secrets/environment configuration.

5. The contact form flow uses `Contact` in `app/models/contact.rb` plus `ContactsController`. Submitted contact data is validated, then handed off to `UserMailer` (`app/mailers/user_mailer.rb`) to send an email to the site owner. This is an outbound email boundary rather than persistent storage.

6. Email delivery is configured around `Action Mailer` and the `user_mailer` view templates. In development/production, SMTP credentials are expected to come from SendGrid-related environment variables, while the destination owner address is also injected through secrets.

7. There is no real application database domain here. Although Rails ActiveRecord is present and SQLite is included, the README makes clear user-submitted data is not meant to be stored locally; ActiveRecord is mainly used for form validation and Rails conventions, not as a business data store.

8. Static content is intentionally separated from dynamic flows. The About page comes from `high_voltage`, which lets Rails render fixed content while still using the shared site layout, navigation, and footer.

9. The front-end assets are managed through Rails’ asset pipeline (`app/assets`). JavaScript and CSS entrypoints are present for the app bundle, and the layout partials provide global UI elements such as navigation and flash messages.

10. Configuration is environment-driven and centralized in `config/secrets.yml`: SendGrid credentials, MailChimp API key/list ID, site domain, owner email, and `secret_key_base`. That makes external integrations and deployment-sensitive settings the main operational boundary.

11. Runtime and deployment are standard Rails: Puma serves the app, and the README describes Heroku deployment with env vars mapped into the app’s secrets. Action Cable, jobs, and other Rails subsystems are present mostly as framework scaffolding, not as core architecture.

12. Test coverage reflects the architecture: an integration test for the home page flow, model tests for `Visitor`, and mailer tests/previews for `UserMailer`. That mirrors the two important business paths—newsletter signup and contact email—plus the static home page.

Main entry points: [`app/views/layouts/application.html.erb`](https://github.com/railsapps/learn-rails/blob/master/app/views/layouts/application.html.erb) (App layout), [`app/controllers/visitors_controller.rb`](https://github.com/railsapps/learn-rails/blob/master/app/controllers/visitors_controller.rb) (Visitors), [`app/controllers/contacts_controller.rb`](https://github.com/railsapps/learn-rails/blob/master/app/controllers/contacts_controller.rb) (Contacts), [`config/routes.rb`](https://github.com/railsapps/learn-rails/blob/master/config/routes.rb) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_layout["App layout<br/>View layout"]
  node_navigation["Navigation<br/>Partial"]
  node_messages["Messages<br/>Partial<br/>[_messages.html.erb]"]
  node_visitors_view["Home page<br/>View<br/>[new.html.erb]"]
  node_contacts_view["Contact form<br/>View<br/>[new.html.erb]"]
  node_about_view["About page<br/>Static page<br/>[about.html.erb]"]
end

subgraph group_flows["Business flows"]
  node_visitors_controller["Visitors<br/>Controller"]
  node_visitor_model[("Visitor<br/>Model/validation<br/>[visitor.rb]")]
  node_contacts_controller["Contacts<br/>Controller"]
  node_contact_model[("Contact<br/>Model/validation<br/>[contact.rb]")]
end

subgraph group_integrations["External integrations"]
  node_user_mailer["User mailer<br/>[user_mailer.rb]"]
  node_mailer_views["Mail views<br/>Email templates"]
  node_mailchimp(("MailChimp<br/>External API"))
  node_smtp(("SMTP/SendGrid<br/>Delivery service"))
end

subgraph group_config["Configuration"]
  node_routes["Routes<br/>Rails routing<br/>[routes.rb]"]
  node_secrets["Secrets<br/>Env config<br/>[secrets.yml]"]
  node_asset_pipeline["Assets<br/>Asset pipeline"]
  node_puma["Puma<br/>Runtime<br/>[puma.rb]"]
end

subgraph group_tests["Tests"]
  node_home_test["Home test<br/>Integration test<br/>[home_page_test.rb]"]
  node_visitor_test["Visitor test<br/>Model test<br/>[visitor_test.rb]"]
  node_mailer_test["Mailer test"]
  node_mailer_preview["Mailer preview"]
end

node_routes -->|"home/signup"| node_visitors_controller
node_routes -->|"contact"| node_contacts_controller
node_routes -->|"static page"| node_about_view
node_visitors_controller -->|"validate"| node_visitor_model
node_visitors_controller -->|"subscribe"| node_mailchimp
node_visitor_model -.->|"credentials"| node_secrets
node_contacts_controller -->|"validate"| node_contact_model
node_contacts_controller -->|"deliver"| node_user_mailer
node_user_mailer -->|"render"| node_mailer_views
node_user_mailer -->|"send"| node_smtp
node_smtp -.->|"auth"| node_secrets
node_app_layout -->|"includes"| node_navigation
node_app_layout -->|"includes"| node_messages
node_app_layout -->|"loads assets"| node_asset_pipeline
node_visitors_controller -->|"renders"| node_visitors_view
node_contacts_controller -->|"renders"| node_contacts_view
node_about_view -->|"uses layout"| node_app_layout
node_visitors_view -->|"uses layout"| node_app_layout
node_contacts_view -->|"uses layout"| node_app_layout
node_home_test -.->|"covers"| node_visitors_controller
node_visitor_test -.->|"covers"| node_visitor_model
node_mailer_test -.->|"covers"| node_user_mailer
node_mailer_preview -.->|"covers"| node_mailer_views
node_puma -->|"serves"| node_routes

click node_routes "https://github.com/railsapps/learn-rails/blob/master/config/routes.rb"
click node_app_layout "https://github.com/railsapps/learn-rails/blob/master/app/views/layouts/application.html.erb"
click node_navigation "https://github.com/railsapps/learn-rails/blob/master/app/views/layouts/_navigation.html.erb"
click node_messages "https://github.com/railsapps/learn-rails/blob/master/app/views/layouts/_messages.html.erb"
click node_visitors_view "https://github.com/railsapps/learn-rails/blob/master/app/views/visitors/new.html.erb"
click node_contacts_view "https://github.com/railsapps/learn-rails/blob/master/app/views/contacts/new.html.erb"
click node_about_view "https://github.com/railsapps/learn-rails/blob/master/app/views/pages/about.html.erb"
click node_visitors_controller "https://github.com/railsapps/learn-rails/blob/master/app/controllers/visitors_controller.rb"
click node_visitor_model "https://github.com/railsapps/learn-rails/blob/master/app/models/visitor.rb"
click node_contacts_controller "https://github.com/railsapps/learn-rails/blob/master/app/controllers/contacts_controller.rb"
click node_contact_model "https://github.com/railsapps/learn-rails/blob/master/app/models/contact.rb"
click node_user_mailer "https://github.com/railsapps/learn-rails/blob/master/app/mailers/user_mailer.rb"
click node_mailer_views "https://github.com/railsapps/learn-rails/blob/master/app/views/user_mailer/contact_email.html.erb"
click node_secrets "https://github.com/railsapps/learn-rails/blob/master/config/secrets.yml"
click node_asset_pipeline "https://github.com/railsapps/learn-rails/blob/master/app/assets/stylesheets/application.css.scss"
click node_puma "https://github.com/railsapps/learn-rails/blob/master/config/puma.rb"
click node_home_test "https://github.com/railsapps/learn-rails/blob/master/test/integration/home_page_test.rb"
click node_visitor_test "https://github.com/railsapps/learn-rails/blob/master/test/models/visitor_test.rb"
click node_mailer_test "https://github.com/railsapps/learn-rails/blob/master/test/mailers/user_mailer_test.rb"
click node_mailer_preview "https://github.com/railsapps/learn-rails/blob/master/test/mailers/previews/user_mailer_preview.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_navigation,node_messages,node_visitors_view,node_contacts_view,node_about_view toneBlue
class node_visitors_controller,node_visitor_model,node_contacts_controller,node_contact_model toneAmber
class node_user_mailer,node_mailer_views,node_mailchimp,node_smtp toneMint
class node_routes,node_secrets,node_asset_pipeline,node_puma toneRose
class node_home_test,node_visitor_test,node_mailer_test,node_mailer_preview toneIndigo
```

## Components

### Presentation

Shared layout and server-rendered pages

- [App layout](https://github.com/railsapps/learn-rails/blob/master/app/views/layouts/application.html.erb): View layout · Shared site chrome and page composition · `app/views/layouts/application.html.erb`
- [Navigation](https://github.com/railsapps/learn-rails/blob/master/app/views/layouts/_navigation.html.erb): Partial · Global menu links · `app/views/layouts/_navigation.html.erb`
- [Messages](https://github.com/railsapps/learn-rails/blob/master/app/views/layouts/_messages.html.erb): Partial · Flash and status messaging · `app/views/layouts/_messages.html.erb`
- [Home page](https://github.com/railsapps/learn-rails/blob/master/app/views/visitors/new.html.erb): View · Signup landing page · `app/views/visitors/new.html.erb`
- [Contact form](https://github.com/railsapps/learn-rails/blob/master/app/views/contacts/new.html.erb): View · Contact submission page · `app/views/contacts/new.html.erb`
- [About page](https://github.com/railsapps/learn-rails/blob/master/app/views/pages/about.html.erb): Static page · High Voltage served content · `app/views/pages/about.html.erb`

### Business flows

Visitor signup and contact submission

- [Visitors](https://github.com/railsapps/learn-rails/blob/master/app/controllers/visitors_controller.rb): Controller · Handles homepage and mailing-list signup · `app/controllers/visitors_controller.rb`
- [Visitor](https://github.com/railsapps/learn-rails/blob/master/app/models/visitor.rb): Model/validation · Validates signup email before mailing-list submit · `app/models/visitor.rb`
- [Contacts](https://github.com/railsapps/learn-rails/blob/master/app/controllers/contacts_controller.rb): Controller · Handles contact form submission · `app/controllers/contacts_controller.rb`
- [Contact](https://github.com/railsapps/learn-rails/blob/master/app/models/contact.rb): Model/validation · Validates contact form input · `app/models/contact.rb`

### External integrations

Mailing list and outbound email boundaries

- [User mailer](https://github.com/railsapps/learn-rails/blob/master/app/mailers/user_mailer.rb): Mailer · Builds outbound contact email · `app/mailers/user_mailer.rb`
- [Mail views](https://github.com/railsapps/learn-rails/blob/master/app/views/user_mailer/contact_email.html.erb): Email templates · HTML and text email bodies · `app/views/user_mailer/contact_email.html.erb`
- **MailChimp**: External API · Newsletter signup destination via Gibbon
- **SMTP/SendGrid**: Delivery service · Outbound email transport for mailer delivery

### Configuration

Routing, secrets, and runtime setup

- [Routes](https://github.com/railsapps/learn-rails/blob/master/config/routes.rb): Rails routing · Main request boundary and route dispatch · `config/routes.rb`
- [Secrets](https://github.com/railsapps/learn-rails/blob/master/config/secrets.yml): Env config · External credentials and deployment-sensitive settings · `config/secrets.yml`
- [Assets](https://github.com/railsapps/learn-rails/blob/master/app/assets/stylesheets/application.css.scss): Asset pipeline · Front-end JS/CSS bundling and shared styling · `app/assets/stylesheets/application.css.scss`
- [Puma](https://github.com/railsapps/learn-rails/blob/master/config/puma.rb): Runtime · Rails app server · `config/puma.rb`

### Tests

Coverage for the main user-facing paths

- [Home test](https://github.com/railsapps/learn-rails/blob/master/test/integration/home_page_test.rb): Integration test · Covers the homepage signup flow · `test/integration/home_page_test.rb`
- [Visitor test](https://github.com/railsapps/learn-rails/blob/master/test/models/visitor_test.rb): Model test · Covers visitor validation · `test/models/visitor_test.rb`
- [Mailer test](https://github.com/railsapps/learn-rails/blob/master/test/mailers/user_mailer_test.rb): Mailer test · Covers contact email delivery behavior · `test/mailers/user_mailer_test.rb`
- [Mailer preview](https://github.com/railsapps/learn-rails/blob/master/test/mailers/previews/user_mailer_preview.rb): Preview · Preview for contact email templates · `test/mailers/previews/user_mailer_preview.rb`

## Connections

- Routes → Visitors: home/signup · Routes dispatch the visitor-facing homepage flow
- Routes → Contacts: contact · Routes dispatch the contact form flow
- Routes → About page: static page · Routes expose static content through High Voltage
- Visitors → Visitor: validate · Signup input is validated before external submission
- Visitors → MailChimp: subscribe · Valid emails are sent to MailChimp through Gibbon
- Visitor → Secrets: credentials · MailChimp API settings are sourced from secrets or environment
- Contacts → Contact: validate · Contact data is validated before email handoff
- Contacts → User mailer: deliver · Valid contact submissions are passed to the mailer
- User mailer → Mail views: render · Mailer composes HTML and text email bodies from templates
- User mailer → SMTP/SendGrid: send · Action Mailer delivers through SMTP/SendGrid
- SMTP/SendGrid → Secrets: auth · SMTP credentials and owner address come from secrets or env
- App layout → Navigation: includes · Shared layout renders navigation partial
- App layout → Messages: includes · Shared layout renders flash/message partial
- App layout → Assets: loads assets · Layout pulls in bundled styles and scripts
- Visitors → Home page: renders · Visitor flow renders the homepage template
- Contacts → Contact form: renders · Contact flow renders the form template
- About page → App layout: uses layout · Static content is wrapped by the shared site chrome
- Home page → App layout: uses layout · Homepage is served within the shared layout
- Contact form → App layout: uses layout · Contact page is served within the shared layout
- Home test → Visitors: covers · Integration test exercises the homepage flow
- Visitor test → Visitor: covers · Model test exercises signup validation
- Mailer test → User mailer: covers · Mailer test exercises outbound contact email
- Mailer preview → Mail views: covers · Preview exercises the email templates
- Puma → Routes: serves · Puma hosts the Rails application entry point
