# shoebtamboli/ecommerce_app architecture

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

- Interactive diagram: https://gitdiagram.com/shoebtamboli/ecommerce_app
- Repository: https://github.com/shoebtamboli/ecommerce_app

## Overview

1. This is a single Ruby on Rails 7 e-commerce monolith. The main application boundary is the Rails app itself: controllers, models, views, jobs, mailers, and policies all live in one codebase and share the same PostgreSQL-backed domain data.

2. The core domain model is small and explicit: `User`, `Product`, `Cart`, `CartItem`, `Order`, `OrderItem`, and `ContactSubmission`. These tables form the main data flow from browsing products, to cart management, to checkout and post-purchase notifications.

3. Public storefront traffic is handled by `PagesController`, `ProductsController`, `CartsController`, and `OrdersController`. These controllers render ERB views under `app/views/pages`, `products`, `carts`, and `orders`, which suggests a server-rendered storefront rather than a separate SPA frontend.

4. The checkout flow is centered on cart-to-order conversion. Users add/remove items and update quantities in `Cart`/`CartItem`; checkout creates an `Order` plus associated `OrderItem` rows, then clears or finalizes the cart. The readme indicates a confirmation email is sent after successful order creation.

5. Admin functionality is segregated under the `admin` namespace with its own layout. `Admin::DashboardController`, `Admin::ProductsController`, `Admin::OrdersController`, and `Admin::UsersController` provide CRUD, order status management, and summary analytics. This is a separate authorization boundary from the storefront.

6. Authentication is handled by Devise, with the generated view set under `app/views/devise`. Authorization is handled by Pundit, with at least `ProductPolicy` present. The `User` model therefore carries role-based access control, likely distinguishing regular shoppers from admins.

7. Background and email processing are first-class subsystems. `OrderMailer` and `ContactMailer` render both HTML and text templates, while `SendOrderConfirmationEmailJob` and `SendOrderStatusUpdateEmailJob` move email delivery off the request path. Sidekiq is listed in the readme as the job backend, so asynchronous work is part of the deployment architecture.

8. Product media is stored through Active Storage, with dedicated migration tables already present. That means product images are not kept directly in the product record but are attached via Rails storage infrastructure, separating binary asset handling from the catalog data.

9. The UI stack is mostly Rails-native: ERB templates, Tailwind CSS builds, and a small Stimulus setup under `app/javascript/controllers`. There is also a `Chart.js`-backed analytics claim in the readme, likely used in the admin dashboard. Pagination is provided by Kaminari, visible from both the dependency and the custom paginator partials.

10. There is a contact form pipeline separate from checkout. Submissions are stored as `ContactSubmission` records and trigger an email via `ContactMailer`, giving the app a second inbound form-to-email workflow besides orders.

11. Routing and layout structure reinforce the split between public and admin surfaces. The app has separate application and admin layouts, plus shared navbar/footer partials for the storefront. Static content lives in `PagesController` and dedicated views such as About, Contact, Privacy Policy, and Terms of Service.

12. The repository also shows an unusual test split: both RSpec under `spec/` and Rails Minitest under `test/` are present. That means the codebase is exercised by two parallel test suites, which is relevant when drawing the engineering and verification boundaries.

13. Operationally, the app is containerized and process-managed for development/runtime with Docker, Puma, and a `Procfile.dev`. Redis is required for Sidekiq, and PostgreSQL is the primary database, so the deployment shape is a Rails web process plus background worker process plus database, with mail captured in development via MailCatcher.

Main entry points: [`config/routes.rb`](https://github.com/shoebtamboli/ecommerce_app/blob/main/config/routes.rb) (Routes), [`app/models`](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/models) (Domain models), [`app/views`](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/views) (Storefront views), [`app/controllers/orders_controller.rb`](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/orders_controller.rb) (Orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Storefront"]
  node_storefront_pages["Static pages<br/>pages controller"]
  node_products_ctrl["Products<br/>storefront controller"]
  node_carts_ctrl["Cart<br/>storefront controller"]
  node_orders_ctrl["Orders<br/>checkout controller"]
  node_storefront_views["Storefront views<br/>erb views"]
  node_contact_submission["Contact form<br/>inbound workflow"]
  node_order_workflow[("Checkout flow<br/>commerce workflow<br/>[order.rb]")]
end

subgraph group_admin["Admin"]
  node_admin_dashboard["Dashboard<br/>admin controller"]
  node_admin_products["Admin products<br/>admin controller"]
  node_admin_orders["Admin orders<br/>admin controller"]
  node_admin_users["Admin users<br/>admin controller"]
end

subgraph group_platform["Platform"]
  node_application["Rails app<br/>monolith<br/>[application.rb]"]
  node_routes["Routes<br/>routing<br/>[routes.rb]"]
  node_auth["Devise<br/>authentication"]
  node_policy["Pundit<br/>authorization<br/>[product_policy.rb]"]
  node_domain[("Domain models<br/>ActiveRecord models")]
  node_storage[("Active Storage<br/>file storage")]
  node_jobs["Jobs<br/>async work"]
  node_mailers["Mailers<br/>email"]
  node_layout["Layouts<br/>presentation shell"]
end

node_routes -->|"public pages"| node_storefront_pages
node_routes -->|"catalog"| node_products_ctrl
node_routes -->|"cart"| node_carts_ctrl
node_routes -->|"checkout"| node_orders_ctrl
node_routes -->|"admin"| node_admin_dashboard
node_routes -->|"admin"| node_admin_products
node_routes -->|"admin"| node_admin_orders
node_routes -->|"admin"| node_admin_users
node_products_ctrl -->|"reads catalog"| node_domain
node_carts_ctrl -->|"updates cart"| node_domain
node_orders_ctrl -->|"creates orders"| node_domain
node_orders_ctrl -->|"enqueue email"| node_jobs
node_admin_products -->|"manages products"| node_domain
node_admin_orders -->|"updates orders"| node_domain
node_admin_users -->|"manages users"| node_domain
node_admin_dashboard -->|"analytics"| node_domain
node_contact_submission -->|"sends email"| node_mailers
node_order_workflow -->|"backgrounds"| node_jobs
node_mailers -->|"renders"| node_layout
node_auth -->|"user auth"| node_domain
node_policy -->|"guards"| node_admin_products
node_policy -->|"guards"| node_admin_orders
node_policy -->|"guards"| node_admin_users
node_storefront_views -->|"uses"| node_layout
node_storefront_pages -->|"renders"| node_storefront_views
node_products_ctrl -->|"renders"| node_storefront_views
node_carts_ctrl -->|"renders"| node_storefront_views
node_orders_ctrl -->|"renders"| node_storefront_views
node_storage -->|"attachments"| node_domain
node_admin_dashboard -->|"login"| node_auth
node_admin_products -->|"authorize"| node_policy

click node_application "https://github.com/shoebtamboli/ecommerce_app/blob/main/config/application.rb"
click node_routes "https://github.com/shoebtamboli/ecommerce_app/blob/main/config/routes.rb"
click node_auth "https://github.com/shoebtamboli/ecommerce_app/tree/main/app/views/devise"
click node_policy "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/policies/product_policy.rb"
click node_domain "https://github.com/shoebtamboli/ecommerce_app/tree/main/app/models"
click node_storage "https://github.com/shoebtamboli/ecommerce_app/blob/main/db/migrate/20240716212842_create_active_storage_tables.active_storage.rb"
click node_jobs "https://github.com/shoebtamboli/ecommerce_app/tree/main/app/jobs"
click node_mailers "https://github.com/shoebtamboli/ecommerce_app/tree/main/app/mailers"
click node_layout "https://github.com/shoebtamboli/ecommerce_app/tree/main/app/views/layouts"
click node_storefront_pages "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/pages_controller.rb"
click node_products_ctrl "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/products_controller.rb"
click node_carts_ctrl "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/carts_controller.rb"
click node_orders_ctrl "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/orders_controller.rb"
click node_storefront_views "https://github.com/shoebtamboli/ecommerce_app/tree/main/app/views"
click node_admin_dashboard "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/dashboard_controller.rb"
click node_admin_products "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/products_controller.rb"
click node_admin_orders "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/orders_controller.rb"
click node_admin_users "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/users_controller.rb"
click node_contact_submission "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/models/contact_submission.rb"
click node_order_workflow "https://github.com/shoebtamboli/ecommerce_app/blob/main/app/models/order.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_storefront_pages,node_products_ctrl,node_carts_ctrl,node_orders_ctrl,node_storefront_views,node_contact_submission,node_order_workflow toneBlue
class node_admin_dashboard,node_admin_products,node_admin_orders,node_admin_users toneAmber
class node_application,node_routes,node_auth,node_policy,node_domain,node_storage,node_jobs,node_mailers,node_layout toneMint
```

## Components

### Storefront

Public browsing, cart, checkout, and static pages

- [Static pages](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/pages_controller.rb): pages controller · Home, about, contact, privacy, and terms content · `app/controllers/pages_controller.rb`
- [Products](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/products_controller.rb): storefront controller · Catalog browsing and product detail pages · `app/controllers/products_controller.rb`
- [Cart](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/carts_controller.rb): storefront controller · Add, remove, and update cart items · `app/controllers/carts_controller.rb`
- [Orders](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/orders_controller.rb): checkout controller · Checkout and order presentation flow · `app/controllers/orders_controller.rb`
- [Storefront views](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/views): erb views · Server-rendered public pages for browsing and checkout · `app/views`
- [Contact form](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/models/contact_submission.rb): inbound workflow · Contact submissions stored and emailed separately from checkout · `app/models/contact_submission.rb`
- [Checkout flow](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/models/order.rb): commerce workflow · Cart-to-order conversion with order items and confirmation email · `app/models/order.rb`

### Admin

Authenticated management surface for catalog, orders, and users

- [Dashboard](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/dashboard_controller.rb): admin controller · Admin overview and summary analytics · `app/controllers/admin/dashboard_controller.rb`
- [Admin products](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/products_controller.rb): admin controller · Catalog CRUD and product management · `app/controllers/admin/products_controller.rb`
- [Admin orders](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/orders_controller.rb): admin controller · Order review and status updates · `app/controllers/admin/orders_controller.rb`
- [Admin users](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/controllers/admin/users_controller.rb): admin controller · User administration and role management · `app/controllers/admin/users_controller.rb`

### Platform

Shared Rails app layer, domain model, auth, jobs, mail, and infrastructure

- [Rails app](https://github.com/shoebtamboli/ecommerce_app/blob/main/config/application.rb): monolith · Single Rails 7 e-commerce application boundary · `config/application.rb`
- [Routes](https://github.com/shoebtamboli/ecommerce_app/blob/main/config/routes.rb): routing · Dispatches public and admin request surfaces · `config/routes.rb`
- [Devise](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/views/devise): authentication · User login, registration, confirmation, and account views · `app/views/devise`
- [Pundit](https://github.com/shoebtamboli/ecommerce_app/blob/main/app/policies/product_policy.rb): authorization · Policy layer governing privileged actions · `app/policies/product_policy.rb`
- [Domain models](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/models): ActiveRecord models · Core commerce entities and contact submissions · `app/models`
- [Active Storage](https://github.com/shoebtamboli/ecommerce_app/blob/main/db/migrate/20240716212842_create_active_storage_tables.active_storage.rb): file storage · Attached product media and blob metadata · `db/migrate/20240716212842_create_active_storage_tables.active_storage.rb`
- [Jobs](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/jobs): async work · Background email delivery for orders and status updates · `app/jobs`
- [Mailers](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/mailers): email · Order and contact notification mail generation · `app/mailers`
- [Layouts](https://github.com/shoebtamboli/ecommerce_app/tree/main/app/views/layouts): presentation shell · Shared storefront and admin layout chrome · `app/views/layouts`

## Connections

- Routes → Static pages: public pages · Routes direct requests to static storefront content
- Routes → Products: catalog · Routes product browsing requests
- Routes → Cart: cart · Routes cart mutation and display requests
- Routes → Orders: checkout · Routes order creation and display requests
- Routes → Dashboard: admin · Routes authenticated admin surface
- Routes → Admin products: admin · Routes admin catalog management
- Routes → Admin orders: admin · Routes admin order management
- Routes → Admin users: admin · Routes admin user management
- Products → Domain models: reads catalog · Loads product data for storefront browsing
- Cart → Domain models: updates cart · Mutates cart and cart item records
- Orders → Domain models: creates orders · Converts cart state into order and order item records
- Orders → Jobs: enqueue email · Triggers confirmation delivery asynchronously
- Admin products → Domain models: manages products · Admin CRUD over product records
- Admin orders → Domain models: updates orders · Admin status changes on order records
- Admin users → Domain models: manages users · Admin CRUD and role changes for users
- Dashboard → Domain models: analytics · Aggregates commerce data for summaries and charts
- Contact form → Mailers: sends email · Contact submissions render notification mail
- Checkout flow → Jobs: backgrounds · Confirmation and status emails run off the request path
- Mailers → Layouts: renders · Mailers use dedicated HTML and text layouts
- Devise → Domain models: user auth · Authentication and account state live on User records
- Pundit → Admin products: guards · Authorization boundary for privileged catalog actions
- Pundit → Admin orders: guards · Authorization boundary for privileged order actions
- Pundit → Admin users: guards · Authorization boundary for privileged user actions
- Storefront views → Layouts: uses · Shared chrome for public server-rendered pages
- Static pages → Storefront views: renders · Static content pages are ERB-rendered
- Products → Storefront views: renders · Catalog pages are ERB-rendered
- Cart → Storefront views: renders · Cart pages are ERB-rendered
- Orders → Storefront views: renders · Checkout and order pages are ERB-rendered
- Active Storage → Domain models: attachments · Product media is attached through Active Storage
- Dashboard → Devise: login · Admin surface relies on Devise-backed accounts
- Admin products → Pundit: authorize · Admin catalog actions are policy-protected
