# restream/redmine_custom_reports architecture

> Architecture diagram of the GitHub repository restream/redmine_custom_reports, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/restream/redmine_custom_reports
- Repository: https://github.com/restream/redmine_custom_reports

## Overview

##### Project type and purpose
- This is a Ruby on Rails plugin for Redmine (a project management web app).
- Its purpose is to allow users to define “Custom Reports” (with filters, grouping, and multiple data series) and render them as interactive charts.

##### File structure
- app/controllers: defines a CustomReportsController that handles HTTP requests for listing, creating, editing, deleting reports.
- app/models: two domain models—CustomReport and CustomReportSeries—plus a query extension.
- app/views: ERB templates that render HTML forms and chart containers.
- assets/javascripts & stylesheets: custom JS (custom_report_charts.js, custom_report_edit.js) plus D3/NVD3 libraries; CSS for charts.
- config/routes.rb: mounts plugin routes under the Redmine UI.
- db/migrate: migrations to create plugin-specific tables.
- lib/redmine_custom_reports: initialization code plus patches to Redmine’s Project and User models.
- init.rb: plugin registration entry point for Redmine.

##### README for additional insights
- Confirms use of d3.js and NVD3 for charting.
- Describes permission model (View vs Manage custom reports).
- Explains Redmine plugin installation and compatibility.

##### Main components and interactions
a. Components
– Redmine Core (Rails app, controllers, models for Issues, Projects, Users)
– Custom Reports Plugin module
- init.rb & lib/… (hook into Redmine startup; monkey-patch models)
- Plugin MVC: CustomReportsController, CustomReport and CustomReportSeries models, views
- Assets: JavaScript chart code + D3/NVD3 + CSS
- Database tables: custom_reports, custom_report_series
– Browser (end-user UI)
– Database (MySQL or PostgreSQL, shared with Redmine core)
– External Libraries: D3.js, NVD3

b. Interactions & Data Flow
1. User’s browser requests a plugin route (e.g., GET /projects/:id/custom_reports).
2. Rails router (config/routes.rb) dispatches to CustomReportsController.
3. Controller uses plugin models (and Redmine’s Issue/query logic via query_ext.rb) to assemble data.
4. Controller queries DB (custom_reports tables + Redmine’s issues tables).
5. Controller renders an ERB view, injecting chart container and data endpoints.
6. Browser loads assets (custom_report_charts.js, d3.v2.js, nv.d3.js).
7. JavaScript fetches JSON data (via endpoints) and renders charts client-side.

c. Architectural patterns & design principles
– Rails MVC inside a Redmine plugin (Engine-style)
– Monkey-patch extensions (ProjectPatch, UserPatch) to hook into Redmine core
– RESTful controller actions for CRUD operations
– Client-heavy chart rendering via D3/NVD3

d. Key technologies
– Ruby on Rails (plugin for Redmine 2.x/3.x)
– ERB templating
– JavaScript: D3.js, NVD3
– Database: MySQL/PostgreSQL
– Testing: Test::Unit functional tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    Browser["Browser (UI)"] 
    subgraph "External Libraries"
        D3["D3.js"]:::external
        NVD3["NVD3.js"]:::external
    end
    subgraph "Redmine Core"
        Router["Rails Router"]:::core
        IssuesController["IssuesController"]:::core
        ProjectModel["Project Model"]:::core
        UserModel["User Model"]:::core
        DBCore["Core DB Tables"]:::db
    end
    subgraph "Custom Reports Plugin"
        Init["init.rb"]:::plugin
        Patches["ProjectPatch & UserPatch"]:::plugin
        Routes["config/routes.rb"]:::plugin
        Controller["CustomReportsController"]:::plugin
        Helper["CustomReportsHelper"]:::plugin
        ModelReport["CustomReport Model"]:::plugin
        ModelSeries["CustomReportSeries Model"]:::plugin
        QueryExt["Query Extension"]:::plugin
        subgraph "Views (ERB)"
            Form["_form.html.erb"]:::plugin
            Links["_links.html.erb"]:::plugin
            Series["_series.html.erb"]:::plugin
            SeriesFilters["_series_filters.html.erb"]:::plugin
            Sidebar["_sidebar.html.erb"]:::plugin
            Edit["edit.html.erb"]:::plugin
            Index["index.html.erb"]:::plugin
            New["new.html.erb"]:::plugin
            Show["show.html.erb"]:::plugin
        end
        subgraph "Assets"
            ChartJS["custom_report_charts.js"]:::plugin
            EditJS["custom_report_edit.js"]:::plugin
            D3Lib["d3.v2.js"]:::plugin
            NVD3Lib["nv.d3.js"]:::plugin
            CSS1["custom_report.css"]:::plugin
            CSS2["nv.d3.css"]:::plugin
        end
        subgraph "Migrations"
            Mig1["20121212125001_create_custom_reports.rb"]:::plugin
            Mig2["20121212125002_create_custom_report_series.rb"]:::plugin
            Mig3["20121212125003_remove_filters_from_custom_reports.rb"]:::plugin
        end
        DBShared["Plugin DB Tables"]:::db
    end

    Browser -->|"loads page"| Router
    Browser -->|"loads assets"| ChartJS
    Browser -->|"loads assets"| EditJS
    ChartJS -->|"uses libs"| D3
    ChartJS -->|"uses libs"| NVD3
    Router -->|"routes to"| Controller
    Controller -->|"uses model"| ModelReport
    Controller -->|"uses model"| ModelSeries
    Controller -->|"uses extension"| QueryExt
    Controller -->|"calls helper"| Helper
    Controller -->|"renders view"| Index
    Controller -->|"renders view"| Show
    Controller -->|"renders view"| New
    Controller -->|"renders view"| Edit
    Controller -->|"renders partial"| Form
    Controller -->|"renders partial"| Links
    Controller -->|"renders partial"| Series
    Controller -->|"renders partial"| SeriesFilters
    Controller -->|"renders partial"| Sidebar
    ModelReport -->|"CRUD operations"| DBShared
    ModelSeries -->|"CRUD operations"| DBShared
    QueryExt -->|"queries issues"| DBCore
    Init -->|"hooks into"| Router
    Init -->|"loads patches"| Patches
    Patches -->|"extend models"| ProjectModel
    Patches -->|"extend models"| UserModel
    Mig1 -->|"create tables"| DBShared
    Mig2 -->|"create tables"| DBShared
    Mig3 -->|"modify tables"| DBShared

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef plugin fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef db fill:#C0C0C0,stroke:#000,stroke-width:1px

    click Controller "https://github.com/restream/redmine_custom_reports/blob/master/app/controllers/custom_reports_controller.rb"
    click Helper "https://github.com/restream/redmine_custom_reports/blob/master/app/helpers/custom_reports_helper.rb"
    click ModelReport "https://github.com/restream/redmine_custom_reports/blob/master/app/models/custom_report.rb"
    click ModelSeries "https://github.com/restream/redmine_custom_reports/blob/master/app/models/custom_report_series.rb"
    click QueryExt "https://github.com/restream/redmine_custom_reports/blob/master/app/models/query_ext.rb"
    click Form "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/_form.html.erb"
    click Links "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/_links.html.erb"
    click Series "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/_series.html.erb"
    click SeriesFilters "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/_series_filters.html.erb"
    click Sidebar "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/_sidebar.html.erb"
    click Edit "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/edit.html.erb"
    click Index "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/index.html.erb"
    click New "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/new.html.erb"
    click Show "https://github.com/restream/redmine_custom_reports/blob/master/app/views/custom_reports/show.html.erb"
    click ChartJS "https://github.com/restream/redmine_custom_reports/blob/master/assets/javascripts/custom_report_charts.js"
    click EditJS "https://github.com/restream/redmine_custom_reports/blob/master/assets/javascripts/custom_report_edit.js"
    click D3Lib "https://github.com/restream/redmine_custom_reports/blob/master/assets/javascripts/d3.v2.js"
    click NVD3Lib "https://github.com/restream/redmine_custom_reports/blob/master/assets/javascripts/nv.d3.js"
    click CSS1 "https://github.com/restream/redmine_custom_reports/blob/master/assets/stylesheets/custom_report.css"
    click CSS2 "https://github.com/restream/redmine_custom_reports/blob/master/assets/stylesheets/nv.d3.css"
    click Routes "https://github.com/restream/redmine_custom_reports/blob/master/config/routes.rb"
    click Mig1 "https://github.com/restream/redmine_custom_reports/blob/master/db/migrate/20121212125001_create_custom_reports.rb"
    click Mig2 "https://github.com/restream/redmine_custom_reports/blob/master/db/migrate/20121212125002_create_custom_report_series.rb"
    click Mig3 "https://github.com/restream/redmine_custom_reports/blob/master/db/migrate/20121212125003_remove_filters_from_custom_reports.rb"
    click Init "https://github.com/restream/redmine_custom_reports/blob/master/init.rb"
    click Patches "https://github.com/restream/redmine_custom_reports/blob/master/lib/redmine_custom_reports/project_patch.rb"
    click Patches "https://github.com/restream/redmine_custom_reports/blob/master/lib/redmine_custom_reports/user_patch.rb"
```
