# melvinthomasdev/wheel architecture

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

- Interactive diagram: https://gitdiagram.com/melvinthomasdev/wheel
- Repository: https://github.com/melvinthomasdev/wheel

## Overview

1. **Overall shape**
   - This is a **single Rails monolith** that serves both server-rendered pages and a React-based frontend.
   - The app is organized around a few distinct surfaces: public pages, authenticated user dashboard, a JSON API under `api/v1`, and an admin area via ActiveAdmin.

2. **Primary runtime boundary**
   - **Rails** is the backend runtime for controllers, models, mailers, jobs, and views.
   - **React** lives inside `app/javascript/src` and is bundled through Webpacker, then mounted from the Rails app.
   - The frontend talks back to Rails through explicit API modules rather than direct model access.

3. **Request flow for the browser UI**
   - A normal browser request hits Rails controllers such as `HomeController`, `PagesController`, `ProfilesController`, and `PasswordsController`.
   - Authenticated user experience is mostly handled by a React application rooted at `app/javascript/src/App.jsx`, which uses route/components for authentication and dashboard flows.
   - Shared layout pieces still come from Rails views and templates in `app/views`.

4. **API subsystem**
   - The versioned API lives under `app/controllers/api/v1`.
   - Main API endpoints are for **sessions, users, notes, and cypress runs**, which suggests the frontend and test automation both depend on this JSON surface.
   - `app/controllers/concerns/api_rescuable.rb` and `api_responders.rb` indicate a standardized error/response contract across API controllers.

5. **Authentication and user state**
   - Authentication is built around **Devise** on the Rails side, with supporting controllers and views for sign-in, password reset, confirmation, and unlock flows.
   - The React side has its own authentication layer with context/reducer state in `app/javascript/src/contexts/auth.jsx` and `reducers/auth.js`.
   - User profile state is similarly separated into a `user` context/reducer, with API clients in `app/javascript/src/apis/authentication.js` and `profiles.js`.

6. **Notes domain**
   - `Note` is the main application domain model besides `User`.
   - Notes have both backend CRUD handling and a React management UI under `components/Dashboard/Notes`, including table, create/edit panes, and delete confirmation.
   - This makes notes a classic end-to-end feature: Rails model/controller/API on one side, React stateful UI on the other.

7. **Dashboard and settings**
   - The authenticated dashboard is divided into **Notes** and **Settings**.
   - Settings includes profile, email, and password management, with a custom password-confirmation modal flow.
   - Reusable UI helpers such as `Sidebar`, `PrivateRoute`, and `EmptyState` form the shared dashboard shell.

8. **Admin and internal operations**
   - `app/admin` contains an **ActiveAdmin** interface, separate from the user-facing app.
   - Admin routes are isolated in `config/routes/active_admin.rb`, which creates a distinct administrative boundary for staff operations.
   - This is an important architecture split: public app, authenticated app, and internal admin are all in the same codebase but route-separated.

9. **Background work and asynchronous processing**
   - Background jobs are defined under `app/workers`, with a shared `BaseWorker`.
   - There is a dedicated worker for `cypress_runs`, plus an `event_notification_worker`, implying async processing for test orchestration and notifications.
   - **Sidekiq** is configured in the app, so job execution is expected to run outside the web process.

10. **Messaging and external services**
   - The app supports email delivery through Rails mailers, with environment-specific interception configured for non-production.
   - **Honeybadger** is wired in for error reporting and context tracking.
   - **Active Storage** is present in the database migrations, so file/blob storage is part of the platform even if the current domain is small.

11. **Frontend/tooling pipeline**
   - JavaScript is bundled with **Webpacker**, with source in `app/javascript/src` and entrypoint in `app/javascript/packs/application.js`.
   - Styling uses **Sass plus Tailwind CSS**, with component/layout styles under `app/javascript/stylesheets`.
   - The repo also includes custom ESLint rules, Prettier, RuboCop, and Husky hooks, so code quality is enforced at commit time as well as in CI.

12. **Testing strategy**
   - Unit/integration coverage lives in `test/` using Rails’ test stack, factories, and controller/model/integration tests.
   - End-to-end browser tests are isolated in a separate `cypress-tests/` workspace, with its own config, fixtures, selectors, and routes.
   - That split suggests the UI is validated at two levels: Rails/JS unit tests and full browser flows via Cypress.

13. **Deployment and environment boundaries**
   - The app is designed for local Rails development, Docker-based development, and CI/CD via Semaphore and CircleCI.
   - Environment-specific config exists for development, staging, production, Heroku, and test, showing the application is intended to run in multiple deployment targets.
   - Database is PostgreSQL, and the app ships with setup scripts and seed data for a demo user, which points to a repeatable bootstrap workflow.

14. **Architecture summary for diagramming**
   - Draw this as a **Rails core** with four main outward-facing zones: public pages, authenticated React dashboard, JSON API, and ActiveAdmin.
   - Behind those, show shared domains/models (`User`, `Note`), async workers via Sidekiq, and platform services like mail, storage, and error reporting.
   - Keep Cypress as an external test harness that exercises the app through the browser/API boundary rather than as part of the runtime application.

Main entry points: [`app/controllers/api/v1/base_controller.rb`](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/base_controller.rb) (API base), [`app/models/user.rb`](https://github.com/melvinthomasdev/wheel/blob/main/app/models/user.rb) (Domain models), [`config/routes.rb`](https://github.com/melvinthomasdev/wheel/blob/main/config/routes.rb) (Routes), [`app/controllers/home_controller.rb`](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/home_controller.rb) (Public pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rails["Rails core"]
  node_routes["Routes<br/>[routes.rb]"]
  node_public_ctrl["Public pages<br/>Rails controllers<br/>[home_controller.rb]"]
  node_views["Rails views<br/>ERB/Slim views"]
  node_api_routes["API routes<br/>Route slice<br/>[api.rb]"]
  node_api_base["API base<br/>API controller<br/>[base_controller.rb]"]
  node_api_auth["Sessions<br/>API controller"]
  node_api_users["Users API<br/>API controller"]
  node_api_notes["Notes API<br/>API controller"]
  node_api_cypress["Cypress API<br/>API controller"]
  node_models[("Domain models<br/>ActiveRecord models<br/>[user.rb]")]
  node_mailers["Mailers<br/>Action Mailer<br/>[mailer.rb]"]
end

subgraph group_react["React frontend"]
  node_webpacker["Webpacker pack<br/>JS entrypoint<br/>[application.js]"]
  node_appjsx["App shell<br/>React app<br/>[App.jsx]"]
  node_auth_ui["Auth UI<br/>React auth<br/>[auth.jsx]"]
  node_dashboard["Dashboard<br/>[index.jsx]"]
  node_notes_ui["Notes UI<br/>React feature<br/>[index.jsx]"]
  node_settings_ui["Settings UI<br/>React feature<br/>[index.jsx]"]
  node_api_clients["API clients<br/>JS service layer<br/>[notes.js]"]
end

subgraph group_ops["Ops and tests"]
  node_jobs["Workers<br/>Background jobs<br/>[base_worker.rb]"]
  node_admin["ActiveAdmin<br/>Admin UI<br/>[dashboard.rb]"]
  node_cypress_tests["Cypress<br/>E2E harness<br/>[login.spec.js]"]
  node_services["Platform services<br/>Infra config<br/>[sidekiq.rb]"]
end

node_routes -->|"routes to"| node_public_ctrl
node_routes -->|"mounts"| node_api_routes
node_routes -->|"mounts"| node_admin
node_public_ctrl -->|"renders"| node_views
node_public_ctrl -->|"reads"| node_models
node_api_routes -->|"inherits"| node_api_base
node_api_base -->|"extends"| node_api_auth
node_api_base -->|"extends"| node_api_users
node_api_base -->|"extends"| node_api_notes
node_api_base -->|"extends"| node_api_cypress
node_api_auth -->|"authenticates"| node_models
node_api_users -->|"reads/writes"| node_models
node_api_notes -->|"reads/writes"| node_models
node_api_cypress -->|"enqueues"| node_jobs
node_jobs -->|"uses"| node_services
node_mailers -->|"uses"| node_services
node_admin -->|"manages"| node_models
node_webpacker -->|"loads"| node_appjsx
node_appjsx -->|"navigates to"| node_auth_ui
node_appjsx -->|"navigates to"| node_dashboard
node_dashboard -->|"hosts"| node_notes_ui
node_dashboard -->|"hosts"| node_settings_ui
node_auth_ui -->|"calls"| node_api_clients
node_notes_ui -->|"calls"| node_api_clients
node_settings_ui -->|"calls"| node_api_clients
node_cypress_tests -->|"exercises"| node_routes
node_cypress_tests -->|"exercises"| node_api_routes

click node_routes "https://github.com/melvinthomasdev/wheel/blob/main/config/routes.rb"
click node_public_ctrl "https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/home_controller.rb"
click node_views "https://github.com/melvinthomasdev/wheel/blob/main/app/views/layouts/application.html.erb"
click node_api_routes "https://github.com/melvinthomasdev/wheel/blob/main/config/routes/api.rb"
click node_api_base "https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/base_controller.rb"
click node_api_auth "https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/sessions_controller.rb"
click node_api_users "https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/users_controller.rb"
click node_api_notes "https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/notes_controller.rb"
click node_api_cypress "https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/cypress_runs_controller.rb"
click node_models "https://github.com/melvinthomasdev/wheel/blob/main/app/models/user.rb"
click node_jobs "https://github.com/melvinthomasdev/wheel/blob/main/app/workers/base_worker.rb"
click node_mailers "https://github.com/melvinthomasdev/wheel/blob/main/app/mailers/mailer.rb"
click node_admin "https://github.com/melvinthomasdev/wheel/blob/main/app/admin/dashboard.rb"
click node_webpacker "https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/packs/application.js"
click node_appjsx "https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/App.jsx"
click node_auth_ui "https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/contexts/auth.jsx"
click node_dashboard "https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/components/Dashboard/index.jsx"
click node_notes_ui "https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/components/Dashboard/Notes/index.jsx"
click node_settings_ui "https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/components/Dashboard/Settings/index.jsx"
click node_api_clients "https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/apis/notes.js"
click node_cypress_tests "https://github.com/melvinthomasdev/wheel/blob/main/cypress-tests/cypress/integration/authentication/login.spec.js"
click node_services "https://github.com/melvinthomasdev/wheel/blob/main/config/initializers/sidekiq.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_routes,node_public_ctrl,node_views,node_api_routes,node_api_base,node_api_auth,node_api_users,node_api_notes,node_api_cypress,node_models,node_mailers toneBlue
class node_webpacker,node_appjsx,node_auth_ui,node_dashboard,node_notes_ui,node_settings_ui,node_api_clients toneAmber
class node_jobs,node_admin,node_cypress_tests,node_services toneMint
```

## Components

### Rails core

Backend runtime for web, API, jobs, mailers, and data models.

- [Routes](https://github.com/melvinthomasdev/wheel/blob/main/config/routes.rb): Rails routes · Top-level routing entry that splits public, API, and admin surfaces. · `config/routes.rb`
- [Public pages](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/home_controller.rb): Rails controllers · Server-rendered entrypoints for home, pages, profiles, and password flows. · `app/controllers/home_controller.rb`
- [Rails views](https://github.com/melvinthomasdev/wheel/blob/main/app/views/layouts/application.html.erb): ERB/Slim views · Shared layouts and public/auth templates rendered by Rails. · `app/views/layouts/application.html.erb`
- [API routes](https://github.com/melvinthomasdev/wheel/blob/main/config/routes/api.rb): Route slice · Versioned JSON API routing boundary. · `config/routes/api.rb`
- [API base](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/base_controller.rb): API controller · Shared API controller behavior, response formatting, and rescue handling. · `app/controllers/api/v1/base_controller.rb`
- [Sessions](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/sessions_controller.rb): API controller · Authentication/session endpoints used by the web app. · `app/controllers/api/v1/sessions_controller.rb`
- [Users API](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/users_controller.rb): API controller · User state and profile endpoints. · `app/controllers/api/v1/users_controller.rb`
- [Notes API](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/notes_controller.rb): API controller · CRUD endpoints for the notes domain. · `app/controllers/api/v1/notes_controller.rb`
- [Cypress API](https://github.com/melvinthomasdev/wheel/blob/main/app/controllers/api/v1/cypress_runs_controller.rb): API controller · Test-orchestration endpoint for browser automation runs. · `app/controllers/api/v1/cypress_runs_controller.rb`
- [Domain models](https://github.com/melvinthomasdev/wheel/blob/main/app/models/user.rb): ActiveRecord models · Core persisted domain objects for users and notes. · `app/models/user.rb`
- [Mailers](https://github.com/melvinthomasdev/wheel/blob/main/app/mailers/mailer.rb): Action Mailer · Email delivery and auth-related message templates. · `app/mailers/mailer.rb`

### React frontend

Webpacker-bundled browser app mounted from Rails.

- [Webpacker pack](https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/packs/application.js): JS entrypoint · Browser bundle entry loaded by Rails. · `app/javascript/packs/application.js`
- [App shell](https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/App.jsx): React app · Top-level React application that routes authentication and dashboard flows. · `app/javascript/src/App.jsx`
- [Auth UI](https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/contexts/auth.jsx): React auth · Login, signup, and reset-password screens plus auth state. · `app/javascript/src/contexts/auth.jsx`
- [Dashboard](https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/components/Dashboard/index.jsx): React dashboard · Authenticated shell for notes and settings. · `app/javascript/src/components/Dashboard/index.jsx`
- [Notes UI](https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/components/Dashboard/Notes/index.jsx): React feature · Stateful notes management screens and dialogs. · `app/javascript/src/components/Dashboard/Notes/index.jsx`
- [Settings UI](https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/components/Dashboard/Settings/index.jsx): React feature · Profile, email, password, and confirmation flows. · `app/javascript/src/components/Dashboard/Settings/index.jsx`
- [API clients](https://github.com/melvinthomasdev/wheel/blob/main/app/javascript/src/apis/notes.js): JS service layer · Frontend adapters for authentication, notes, and profile requests. · `app/javascript/src/apis/notes.js`

### Ops and tests

Async processing, admin operations, and browser/e2e validation.

- [Workers](https://github.com/melvinthomasdev/wheel/blob/main/app/workers/base_worker.rb): Background jobs · Async processing for notifications and Cypress runs. · `app/workers/base_worker.rb`
- [ActiveAdmin](https://github.com/melvinthomasdev/wheel/blob/main/app/admin/dashboard.rb): Admin UI · Separate staff-facing administration surface. · `app/admin/dashboard.rb`
- [Cypress](https://github.com/melvinthomasdev/wheel/blob/main/cypress-tests/cypress/integration/authentication/login.spec.js): E2E harness · Browser-level tests that exercise the app through its UI and API. · `cypress-tests/cypress/integration/authentication/login.spec.js`
- [Platform services](https://github.com/melvinthomasdev/wheel/blob/main/config/initializers/sidekiq.rb): Infra config · Sidekiq, storage, and error-reporting integration points. · `config/initializers/sidekiq.rb`

## Connections

- Routes → Public pages: routes to · Public browser requests are dispatched to server-rendered controllers.
- Routes → API routes: mounts · API namespace is separated from the main web routes.
- Routes → ActiveAdmin: mounts · Admin surface is isolated behind its own route layer.
- Public pages → Rails views: renders · Controllers render shared layouts and public/auth templates.
- Public pages → Domain models: reads · Public and profile flows depend on core persisted domain state.
- API routes → API base: inherits · Versioned API controllers share response and error behavior.
- API base → Sessions: extends · Sessions endpoint uses the common API base behavior.
- API base → Users API: extends · Users endpoint uses the common API base behavior.
- API base → Notes API: extends · Notes endpoint uses the common API base behavior.
- API base → Cypress API: extends · Cypress-run endpoint uses the common API base behavior.
- Sessions → Domain models: authenticates · Session handling resolves user identity from persisted data.
- Users API → Domain models: reads/writes · User profile state is persisted through the domain models.
- Notes API → Domain models: reads/writes · Notes CRUD operates on the notes model.
- Cypress API → Workers: enqueues · Cypress-run operations are pushed into background processing.
- Workers → Platform services: uses · Workers run outside the web process with app infrastructure services.
- Mailers → Platform services: uses · Mail delivery relies on environment and interceptor setup.
- ActiveAdmin → Domain models: manages · Admin screens operate on the same underlying domain records.
- Webpacker pack → App shell: loads · Webpacker entry mounts the React application.
- App shell → Auth UI: navigates to · The app shell routes unauthenticated users into auth flows.
- App shell → Dashboard: navigates to · Authenticated users enter the dashboard shell.
- Dashboard → Notes UI: hosts · Notes management is a major dashboard surface.
- Dashboard → Settings UI: hosts · Settings management is the other major dashboard surface.
- Auth UI → API clients: calls · Authentication forms talk to Rails through client modules.
- Notes UI → API clients: calls · Notes UI uses dedicated API adapters rather than direct model access.
- Settings UI → API clients: calls · Settings UI uses profile/auth API adapters.
- Cypress → Routes: exercises · End-to-end tests validate the browser surface through the app routes.
- Cypress → API routes: exercises · E2E flows also depend on the JSON API boundary.
