How melvinthomasdev/granite works
1. Overall shape
- This is a Rails monolith with a React frontend bundled through Webpacker.
- The app serves both server-rendered Rails views and JSON APIs consumed by the React client.
- Background processing is a first-class part of the architecture, via Sidekiq workers/jobs, with email and report generation also handled asynchronously.
2. Request entry points
- Browser traffic enters through config/routes.rb into controllers under app/controllers.
- There are two main response styles:
- HTML pages for the initial app shell, layout, and report download page.
- JSON endpoints for the React app and API-style interactions such as sessions, tasks, comments, preferences, and users.
3. Frontend subsystem
- Client code lives in app/javascript/src, with React components organized by feature: Authentication, Tasks, Comments, Dashboard, MyPreferences, NavBar, etc.
- API calls are isolated in app/javascript/src/apis, with a shared Axios wrapper, so UI components do not talk directly to Rails endpoints.
- PrivateRoute, Toastr, PageLoader, and Container indicate the frontend owns routing guards, transient UI state, and shared presentation concerns.
- Styling is split between Rails asset styles and a Webpacker-managed SCSS pipeline, with Tailwind and custom SCSS both present.
4. Backend domain boundary
- Core domain models are in app/models: Task, User, Comment, Preference, Log, and UserNotification.
- The migration history shows the domain centers on task management, with support for assignment, ownership, status/progress, comments, slugs, and derived counters.
- Preference suggests per-user settings; Log and notification tables support auditing and user-facing events.
5. Authentication and authorization
- Authentication is handled by Rails controllers plus shared concerns in app/controllers/concerns/authenticable.rb.
- Session-related API handling is in SessionsController, with a JSON view for login/create responses.
- Authorization is centralized with app/policies/task_policy.rb, so task actions are governed separately from controller flow.
- The frontend mirrors this boundary with authenticated routes and a private-route component.
6. Task workflow
- TasksController and tasks/reports_controller.rb are the main orchestration points for task-related actions.
- The task feature spans list, show, create, edit, and report/download flows in the React components and Rails views.
- Comments are a subordinate domain, linked to tasks and exposed through both backend controllers and frontend components.
- comments_count, progress, status, slug, and assignment fields imply tasks have lifecycle state and searchable human-friendly URLs.
7. Async processing and notifications
- Background jobs live in app/jobs and app/workers, with Sidekiq configured in config/initializers/sidekiq.rb and config/sidekiq.yml.
- task_logger_job, todo_notifications_worker, user_notifications_worker, and reports_worker indicate the app offloads logging, reminders, user notifications, and report generation.
- TodoNotificationService acts as a domain service boundary between business rules and queue workers.
- Notifications are persisted in user_notifications, suggesting work is not just ephemeral email delivery but also in-app notification records.
8. Email and communication
- TaskMailer and its templates provide transactional email, including pending-task email content.
- Mailer layouts are separated from the main app layout, which is typical for a distinct delivery channel.
- This makes email a parallel output path from the same task/notification domain rather than a separate system.
9. Reporting and document generation
- The reporting flow uses a dedicated controller, a worker, and a PDF-oriented layout under app/views/layouts/pdf.html.erb.
- wicked_pdf is initialized in the app, so reports are likely rendered as HTML and converted to PDF.
- There is a dedicated tasks/report/download.html.erb view, indicating report generation is a distinct pipeline from normal task CRUD.
10. Real-time and event infrastructure
- app/channels/application_cable is present, so ActionCable is enabled at the framework level.
- Even if current feature usage is limited, this is an architectural boundary for real-time updates or future push notifications.
- It sits alongside Sidekiq as the app’s two asynchronous/event-oriented subsystems: one for live connections, one for deferred jobs.
11. Data and persistence
- ActiveRecord migrations define the canonical schema and show the app evolved incrementally around tasks, users, comments, preferences, logs, notifications, and Active Storage.
- active_storage tables are present, so file attachment/storage is part of the persistence model.
- sqlite_custom_regexp_function and schema/test setup files suggest some environment-specific database behavior and a fairly test-driven persistence layer.
12. Deployment and runtime boundary
- Procfile, puma, webpacker-dev-server, and sidekiq configuration imply a multi-process runtime: web, job worker, and asset build processes.
- CircleCI, Husky, ESLint, RuboCop, and test factories indicate the repo is wired for automated linting, CI, and broad test coverage.
- config/scheduled_jobs.yml suggests at least some background tasks are scheduled, not only event-triggered.
13. How data flows through the system
- A typical task request flows from the browser to a Rails controller, through model/policy/service layers, then back as HTML or JSON.
- The React app calls Rails APIs for auth, task, comment, user, and preference operations.
- Some writes trigger side effects: logging, notifications, mail, or report jobs, which are handled asynchronously by Sidekiq workers.
- Generated artifacts include emails, notification records, and downloadable reports/PDFs.
14. Good diagram boundaries
- A clear architecture diagram should separate:
- Browser / React client
- Rails web layer
- Domain models and policies
- Background jobs/workers
- Mail/PDF/reporting outputs
- Persistence layer
- The biggest functional boundary in this repo is between interactive CRUD UI and asynchronous side effects around notifications, logging, and reports.
Main entry points: controllers Controllers · task.rb Task · migrate Schema · workers Workers
Components 23
Client UI
Browser-facing React app and shared frontend assets.
- React App · Webpacker-bundled client application
app/javascript/src/App.jsx - UI Components · Feature components for auth, tasks, comments, nav, and preferences
app/javascript/src/components - API Layer · Shared browser-to-Rails API wrappers
app/javascript/src/apis - Styles · Webpack-managed SCSS and UI styling
app/javascript/stylesheets/application.scss
Rails Web
Routes, controllers, views, and authorization for request handling.
- Routes · Entry routing for web requests
config/routes.rb - Controllers · HTML and JSON request handlers
app/controllers - Auth Guard · Shared authentication and API response behavior
app/controllers/concerns/authenticable.rb - Task Policy · Task-level authorization boundary
app/policies/task_policy.rb - Views · Server-rendered pages, JSON builders, and mail/PDF templates
app/views
Domain
Core models and business rules around tasks and user state.
- Task · Core task lifecycle and assignment domain
app/models/task.rb - User · Accounts, authentication, and ownership
app/models/user.rb - Comment · Task-linked discussion records
app/models/comment.rb - Preference · Per-user settings
app/models/preference.rb - Notifications · Persisted user-facing notification records
app/models/user_notification.rb - Log · Audit and task activity records
app/models/log.rb
Async
Background jobs, workers, and notification/report pipelines.
- Notify Service · Notification rules and worker boundary
app/services/todo_notification_service.rb - Task Logger · Asynchronous task activity logging
app/jobs/task_logger_job.rb - Workers · Report and notification workers
app/workers - Task Mailer · Transactional email delivery
app/mailers/task_mailer.rb - Reports · Report download and PDF generation pipeline
app/controllers/tasks/reports_controller.rb
Data
Persistence and schema evolution.
- Schema · Database schema history and Active Storage tables
db/migrate
Runtime
Process and build-time configuration.
- Sidekiq Config · Background job runtime settings
config/sidekiq.yml - Webpacker · Frontend build and dev-server configuration
config/webpack/environment.js
Connections 31
- Routes → Controllers: dispatches · Routes map browser requests to controller actions
- Controllers → Auth Guard: uses · Controllers share auth and API response behavior
- Controllers → Task Policy: authorizes · Task actions are checked through policy logic
- Controllers → Views: renders · Controllers return HTML pages and JSON templates
- React App → UI Components: composes · App shell is built from feature components
- React App → API Layer: calls · Client data access goes through API wrappers
- React App → Styles: styles · Client uses the SCSS pipeline for presentation
- UI Components → API Layer: loads data · Feature UI fetches and mutates via APIs
- Controllers → Task: operates on · Task controllers orchestrate task domain actions
- Controllers → Comment: operates on · Comment flows are handled through web controllers
- Controllers → User: operates on · Session, user, and preference flows touch users
- Task → Comment: has many · Comments belong to tasks
- Task → User: assigned to · Tasks track owner and assignee relationships
- User → Preference: has one · Users own preferences
- Task → Log: logs · Task activity is recorded as logs
- Task → Notifications: notifies · Task events generate persisted notifications
- Notify Service → Workers: enqueues · Notification logic hands work to background workers
- Workers → Notifications: writes · Workers persist notification records
- Workers → Task Mailer: sends · Workers trigger transactional email delivery
- Workers → Reports: generates · Workers handle async report generation
- Task Logger → Log: persists · Job writes audit and activity logs
- Task Mailer → Views: uses templates · Mailers render dedicated email templates
- Reports → Views: renders pdf · Report flow uses HTML views and PDF layout
- Schema → Task: defines schema · Schema evolves around task storage and lifecycle
- Schema → User: defines schema · Schema defines users and auth fields
- Schema → Comment: defines schema · Schema defines comment storage
- Schema → Notifications: defines schema · Schema defines notification records
- Schema → Preference: defines schema · Schema defines preference records
- Sidekiq Config → Workers: runs · Sidekiq executes background workers
- Webpacker → React App: bundles · Webpacker builds the React client
- Webpacker → Styles: compiles · Webpacker compiles SCSS assets