# melvinthomasdev/granite architecture

> Architecture diagram of the GitHub repository melvinthomasdev/granite, 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/granite
- Repository: https://github.com/melvinthomasdev/granite

## Overview

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: [`app/controllers`](https://github.com/melvinthomasdev/granite/tree/main/app/controllers) (Controllers), [`app/models/task.rb`](https://github.com/melvinthomasdev/granite/blob/main/app/models/task.rb) (Task), [`db/migrate`](https://github.com/melvinthomasdev/granite/tree/main/db/migrate) (Schema), [`app/workers`](https://github.com/melvinthomasdev/granite/tree/main/app/workers) (Workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_react_app["React App<br/>frontend shell<br/>[App.jsx]"]
  node_frontend_components["UI Components<br/>react components"]
  node_frontend_apis["API Layer<br/>axios clients"]
  node_frontend_styles["Styles<br/>scss pipeline<br/>[application.scss]"]
end

subgraph group_web["Rails Web"]
  node_routes["Routes<br/>router<br/>[routes.rb]"]
  node_controllers["Controllers"]
  node_auth_concern["Auth Guard<br/>controller concern<br/>[authenticable.rb]"]
  node_task_policy{{"Task Policy<br/>authorization<br/>[task_policy.rb]"}}
  node_views["Views<br/>templates"]
end

subgraph group_domain["Domain"]
  node_task_model[("Task<br/>AR model<br/>[task.rb]")]
  node_user_model[("User<br/>AR model<br/>[user.rb]")]
  node_comment_model[("Comment<br/>AR model<br/>[comment.rb]")]
  node_preference_model[("Preference<br/>AR model<br/>[preference.rb]")]
  node_notification_model[("Notifications<br/>AR model")]
  node_log_model[("Log<br/>AR model<br/>[log.rb]")]
end

subgraph group_async["Async"]
  node_todo_service["Notify Service<br/>domain service"]
  node_task_logger_job["Task Logger<br/>job<br/>[task_logger_job.rb]"]
  node_workers["Workers"]
  node_mailer["Task Mailer<br/>[task_mailer.rb]"]
  node_reports["Reports<br/>pdf flow"]
end

subgraph group_data["Data"]
  node_migrations[("Schema<br/>migrations")]
end

subgraph group_runtime["Runtime"]
  node_sidekiq["Sidekiq Config<br/>runtime config<br/>[sidekiq.yml]"]
  node_webpack["Webpacker<br/>build config<br/>[environment.js]"]
end

node_routes -->|"dispatches"| node_controllers
node_controllers -->|"uses"| node_auth_concern
node_controllers -->|"authorizes"| node_task_policy
node_controllers -->|"renders"| node_views
node_react_app -->|"composes"| node_frontend_components
node_react_app -->|"calls"| node_frontend_apis
node_react_app -->|"styles"| node_frontend_styles
node_frontend_components -->|"loads data"| node_frontend_apis
node_controllers -->|"operates on"| node_task_model
node_controllers -->|"operates on"| node_comment_model
node_controllers -->|"operates on"| node_user_model
node_task_model -->|"has many"| node_comment_model
node_task_model -->|"assigned to"| node_user_model
node_user_model -->|"has one"| node_preference_model
node_task_model -->|"logs"| node_log_model
node_task_model -->|"notifies"| node_notification_model
node_todo_service -->|"enqueues"| node_workers
node_workers -->|"writes"| node_notification_model
node_workers -->|"sends"| node_mailer
node_workers -->|"generates"| node_reports
node_task_logger_job -->|"persists"| node_log_model
node_mailer -->|"uses templates"| node_views
node_reports -->|"renders pdf"| node_views
node_migrations -->|"defines schema"| node_task_model
node_migrations -->|"defines schema"| node_user_model
node_migrations -->|"defines schema"| node_comment_model
node_migrations -->|"defines schema"| node_notification_model
node_migrations -->|"defines schema"| node_preference_model
node_sidekiq -->|"runs"| node_workers
node_webpack -->|"bundles"| node_react_app
node_webpack -->|"compiles"| node_frontend_styles

click node_routes "https://github.com/melvinthomasdev/granite/blob/main/config/routes.rb"
click node_controllers "https://github.com/melvinthomasdev/granite/tree/main/app/controllers"
click node_auth_concern "https://github.com/melvinthomasdev/granite/blob/main/app/controllers/concerns/authenticable.rb"
click node_task_policy "https://github.com/melvinthomasdev/granite/blob/main/app/policies/task_policy.rb"
click node_views "https://github.com/melvinthomasdev/granite/tree/main/app/views"
click node_react_app "https://github.com/melvinthomasdev/granite/blob/main/app/javascript/src/App.jsx"
click node_frontend_components "https://github.com/melvinthomasdev/granite/tree/main/app/javascript/src/components"
click node_frontend_apis "https://github.com/melvinthomasdev/granite/tree/main/app/javascript/src/apis"
click node_frontend_styles "https://github.com/melvinthomasdev/granite/blob/main/app/javascript/stylesheets/application.scss"
click node_task_model "https://github.com/melvinthomasdev/granite/blob/main/app/models/task.rb"
click node_user_model "https://github.com/melvinthomasdev/granite/blob/main/app/models/user.rb"
click node_comment_model "https://github.com/melvinthomasdev/granite/blob/main/app/models/comment.rb"
click node_preference_model "https://github.com/melvinthomasdev/granite/blob/main/app/models/preference.rb"
click node_notification_model "https://github.com/melvinthomasdev/granite/blob/main/app/models/user_notification.rb"
click node_log_model "https://github.com/melvinthomasdev/granite/blob/main/app/models/log.rb"
click node_todo_service "https://github.com/melvinthomasdev/granite/blob/main/app/services/todo_notification_service.rb"
click node_task_logger_job "https://github.com/melvinthomasdev/granite/blob/main/app/jobs/task_logger_job.rb"
click node_workers "https://github.com/melvinthomasdev/granite/tree/main/app/workers"
click node_mailer "https://github.com/melvinthomasdev/granite/blob/main/app/mailers/task_mailer.rb"
click node_reports "https://github.com/melvinthomasdev/granite/blob/main/app/controllers/tasks/reports_controller.rb"
click node_migrations "https://github.com/melvinthomasdev/granite/tree/main/db/migrate"
click node_sidekiq "https://github.com/melvinthomasdev/granite/blob/main/config/sidekiq.yml"
click node_webpack "https://github.com/melvinthomasdev/granite/blob/main/config/webpack/environment.js"

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_react_app,node_frontend_components,node_frontend_apis,node_frontend_styles toneBlue
class node_routes,node_controllers,node_auth_concern,node_task_policy,node_views toneAmber
class node_task_model,node_user_model,node_comment_model,node_preference_model,node_notification_model,node_log_model toneMint
class node_todo_service,node_task_logger_job,node_workers,node_mailer,node_reports toneRose
class node_migrations toneIndigo
class node_sidekiq,node_webpack toneTeal
```

## Components

### Client UI

Browser-facing React app and shared frontend assets.

- [React App](https://github.com/melvinthomasdev/granite/blob/main/app/javascript/src/App.jsx): frontend shell · Webpacker-bundled client application · `app/javascript/src/App.jsx`
- [UI Components](https://github.com/melvinthomasdev/granite/tree/main/app/javascript/src/components): react components · Feature components for auth, tasks, comments, nav, and preferences · `app/javascript/src/components`
- [API Layer](https://github.com/melvinthomasdev/granite/tree/main/app/javascript/src/apis): axios clients · Shared browser-to-Rails API wrappers · `app/javascript/src/apis`
- [Styles](https://github.com/melvinthomasdev/granite/blob/main/app/javascript/stylesheets/application.scss): scss pipeline · Webpack-managed SCSS and UI styling · `app/javascript/stylesheets/application.scss`

### Rails Web

Routes, controllers, views, and authorization for request handling.

- [Routes](https://github.com/melvinthomasdev/granite/blob/main/config/routes.rb): router · Entry routing for web requests · `config/routes.rb`
- [Controllers](https://github.com/melvinthomasdev/granite/tree/main/app/controllers): web controllers · HTML and JSON request handlers · `app/controllers`
- [Auth Guard](https://github.com/melvinthomasdev/granite/blob/main/app/controllers/concerns/authenticable.rb): controller concern · Shared authentication and API response behavior · `app/controllers/concerns/authenticable.rb`
- [Task Policy](https://github.com/melvinthomasdev/granite/blob/main/app/policies/task_policy.rb): authorization · Task-level authorization boundary · `app/policies/task_policy.rb`
- [Views](https://github.com/melvinthomasdev/granite/tree/main/app/views): templates · Server-rendered pages, JSON builders, and mail/PDF templates · `app/views`

### Domain

Core models and business rules around tasks and user state.

- [Task](https://github.com/melvinthomasdev/granite/blob/main/app/models/task.rb): AR model · Core task lifecycle and assignment domain · `app/models/task.rb`
- [User](https://github.com/melvinthomasdev/granite/blob/main/app/models/user.rb): AR model · Accounts, authentication, and ownership · `app/models/user.rb`
- [Comment](https://github.com/melvinthomasdev/granite/blob/main/app/models/comment.rb): AR model · Task-linked discussion records · `app/models/comment.rb`
- [Preference](https://github.com/melvinthomasdev/granite/blob/main/app/models/preference.rb): AR model · Per-user settings · `app/models/preference.rb`
- [Notifications](https://github.com/melvinthomasdev/granite/blob/main/app/models/user_notification.rb): AR model · Persisted user-facing notification records · `app/models/user_notification.rb`
- [Log](https://github.com/melvinthomasdev/granite/blob/main/app/models/log.rb): AR model · Audit and task activity records · `app/models/log.rb`

### Async

Background jobs, workers, and notification/report pipelines.

- [Notify Service](https://github.com/melvinthomasdev/granite/blob/main/app/services/todo_notification_service.rb): domain service · Notification rules and worker boundary · `app/services/todo_notification_service.rb`
- [Task Logger](https://github.com/melvinthomasdev/granite/blob/main/app/jobs/task_logger_job.rb): job · Asynchronous task activity logging · `app/jobs/task_logger_job.rb`
- [Workers](https://github.com/melvinthomasdev/granite/tree/main/app/workers): sidekiq workers · Report and notification workers · `app/workers`
- [Task Mailer](https://github.com/melvinthomasdev/granite/blob/main/app/mailers/task_mailer.rb): mailer · Transactional email delivery · `app/mailers/task_mailer.rb`
- [Reports](https://github.com/melvinthomasdev/granite/blob/main/app/controllers/tasks/reports_controller.rb): pdf flow · Report download and PDF generation pipeline · `app/controllers/tasks/reports_controller.rb`

### Data

Persistence and schema evolution.

- [Schema](https://github.com/melvinthomasdev/granite/tree/main/db/migrate): migrations · Database schema history and Active Storage tables · `db/migrate`

### Runtime

Process and build-time configuration.

- [Sidekiq Config](https://github.com/melvinthomasdev/granite/blob/main/config/sidekiq.yml): runtime config · Background job runtime settings · `config/sidekiq.yml`
- [Webpacker](https://github.com/melvinthomasdev/granite/blob/main/config/webpack/environment.js): build config · Frontend build and dev-server configuration · `config/webpack/environment.js`

## Connections

- 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
