How melvinthomasdev/wheel works
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: base_controller.rb API base · user.rb Domain models · routes.rb Routes · home_controller.rb Public pages
Components 22
Rails core
Backend runtime for web, API, jobs, mailers, and data models.
- Routes · Top-level routing entry that splits public, API, and admin surfaces.
config/routes.rb - Public pages · Server-rendered entrypoints for home, pages, profiles, and password flows.
app/controllers/home_controller.rb - Rails views · Shared layouts and public/auth templates rendered by Rails.
app/views/layouts/application.html.erb - API routes · Versioned JSON API routing boundary.
config/routes/api.rb - API base · Shared API controller behavior, response formatting, and rescue handling.
app/controllers/api/v1/base_controller.rb - Sessions · Authentication/session endpoints used by the web app.
app/controllers/api/v1/sessions_controller.rb - Users API · User state and profile endpoints.
app/controllers/api/v1/users_controller.rb - Notes API · CRUD endpoints for the notes domain.
app/controllers/api/v1/notes_controller.rb - Cypress API · Test-orchestration endpoint for browser automation runs.
app/controllers/api/v1/cypress_runs_controller.rb - Domain models · Core persisted domain objects for users and notes.
app/models/user.rb - Mailers · Email delivery and auth-related message templates.
app/mailers/mailer.rb
React frontend
Webpacker-bundled browser app mounted from Rails.
- Webpacker pack · Browser bundle entry loaded by Rails.
app/javascript/packs/application.js - App shell · Top-level React application that routes authentication and dashboard flows.
app/javascript/src/App.jsx - Auth UI · Login, signup, and reset-password screens plus auth state.
app/javascript/src/contexts/auth.jsx - Dashboard · Authenticated shell for notes and settings.
app/javascript/src/components/Dashboard/index.jsx - Notes UI · Stateful notes management screens and dialogs.
app/javascript/src/components/Dashboard/Notes/index.jsx - Settings UI · Profile, email, password, and confirmation flows.
app/javascript/src/components/Dashboard/Settings/index.jsx - API clients · 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 · Async processing for notifications and Cypress runs.
app/workers/base_worker.rb - ActiveAdmin · Separate staff-facing administration surface.
app/admin/dashboard.rb - Cypress · Browser-level tests that exercise the app through its UI and API.
cypress-tests/cypress/integration/authentication/login.spec.js - Platform services · Sidekiq, storage, and error-reporting integration points.
config/initializers/sidekiq.rb
Connections 27
- 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.