How shoebtamboli/ecommerce_app works
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: routes.rb Routes · models Domain models · views Storefront views · orders_controller.rb Orders
Components 20
Storefront
Public browsing, cart, checkout, and static pages
- Static pages · Home, about, contact, privacy, and terms content
app/controllers/pages_controller.rb - Products · Catalog browsing and product detail pages
app/controllers/products_controller.rb - Cart · Add, remove, and update cart items
app/controllers/carts_controller.rb - Orders · Checkout and order presentation flow
app/controllers/orders_controller.rb - Storefront views · Server-rendered public pages for browsing and checkout
app/views - Contact form · Contact submissions stored and emailed separately from checkout
app/models/contact_submission.rb - Checkout flow · Cart-to-order conversion with order items and confirmation email
app/models/order.rb
Admin
Authenticated management surface for catalog, orders, and users
- Dashboard · Admin overview and summary analytics
app/controllers/admin/dashboard_controller.rb - Admin products · Catalog CRUD and product management
app/controllers/admin/products_controller.rb - Admin orders · Order review and status updates
app/controllers/admin/orders_controller.rb - Admin users · 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 · Single Rails 7 e-commerce application boundary
config/application.rb - Routes · Dispatches public and admin request surfaces
config/routes.rb - Devise · User login, registration, confirmation, and account views
app/views/devise - Pundit · Policy layer governing privileged actions
app/policies/product_policy.rb - Domain models · Core commerce entities and contact submissions
app/models - Active Storage · Attached product media and blob metadata
db/migrate/20240716212842_create_active_storage_tables.active_storage.rb - Jobs · Background email delivery for orders and status updates
app/jobs - Mailers · Order and contact notification mail generation
app/mailers - Layouts · Shared storefront and admin layout chrome
app/views/layouts
Connections 31
- 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