# harminderbomrah/jira-engine architecture

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

- Interactive diagram: https://gitdiagram.com/harminderbomrah/jira-engine
- Repository: https://github.com/harminderbomrah/jira-engine

## Overview

##### Project Type and Purpose
- This is a Ruby on Rails Engine packaged as a gem (“jira”) that you mount into a host Rails application.
- Its purpose is to integrate Jira (and a “CodeGiant” system) data into a Rails app, providing UI pages, background sync jobs, models, and services.

##### High-Level Architectural Components
a. Host Rails Application
- Your main app that includes this engine via Gemfile.
- Provides the database, routing, asset pipeline, and Sidekiq/ActiveJob infrastructure.
b. Jira Engine (the gem)
- Namespace: lib/jira/engine.rb mounts under `/jira`.
- Contains:
– MVC layers (app/controllers/jira, app/models/jira, app/views/jira).
– Services (app/services/jira/*) for HTTP/GraphQL calls.
– Background Jobs (app/jobs/jira/*) for periodic data sync.
– Mailers (app/mailers/jira/*) for notifications.
– Asset pipeline (app/assets/*) for JS/CSS/images.
c. External Services
- Jira REST (or GraphQL) API
- CodeGiant GraphQL endpoint
d. Database
- Tables for users, projects, issues, comments, histories, field_mappings, import_statuses, priorities, statuses, types, and mappings between Jira/CodeGiant and local users/projects.
e. Sidekiq (or ActiveJob)
- Processes background jobs that fetch and update data asynchronously.
f. OmniAuth (config/initializers/omniauth.rb)
- Handles Jira authentication workflow.

##### Relationships & Data Flow
1. User → UI
- User hits routes under `/jira` served by `Jira::PagesController`, `ProjectsController`, etc.
- Views render data by querying local models.
2. Controller → Service → External API
- Controllers call `Jira::JiraProjectService` or `GraphqlService` for on-demand data.
3. Scheduled/Synchronous Job → Service → Database
- Jobs (`FetchJiraIssuesJob`, `FetchCodeGiantUsersJob`, etc.) invoke service objects, pull data from external APIs, then upsert into ActiveRecord models (Issue, Project, User, etc.).
4. Persistence
- All entities are stored in the host app’s database via ActiveRecord migrations under db/migrate.
5. Notifications
- When certain events occur (issue mapped, import completed), mailers send out emails via `Jira::ApplicationMailer`.

##### Architectural Patterns & Design Principles
- Rails Engine Pattern: Clean isolation of “jira” functionality, mountable gem.
- MVC: Standard Rails model–view–controller separation within the engine.
- Service Objects: Encapsulate external API interactions in `app/services/jira/*`.
- Background Processing: Jobs for retryable, scheduled syncing.
- Dependency Injection/Configuration: Initializers for OAuth, Sidekiq, and asset precompile.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        JiraAPI["Jira REST/GraphQL API"]:::external
        CodeGiantAPI["CodeGiant GraphQL"]:::external
    end

    %% Host Rails Application
    subgraph "Host Rails Application"
        direction TB
        Routes["config/routes.rb"]:::engine
        OmniAuthInit["config/initializers/omniauth.rb"]:::engine
        SidekiqInit["config/initializers/sidekiq.rb"]:::engine
        AssetsInit["config/initializers/assets.rb"]:::engine
        Manifest["app/assets/config/jira_manifest.js"]:::engine
        EngineMount["lib/jira/engine.rb"]:::engine
        subgraph "Sidekiq Worker Pool" 
            direction TB
            Sidekiq["Sidekiq/ActiveJob"]:::background
        end
        DB["Host App Database"]:::db
    end

    %% Jira Engine Gem
    subgraph "Jira Engine (gem)"
        direction TB
        Controllers["app/controllers/jira/*"]:::ui
        Views["app/views/jira/**/*"]:::ui
        Helpers["app/helpers/jira/application_helper.rb"]:::ui
        Models["app/models/jira/*"]:::db
        Services["app/services/jira/*"]:::service
        Jobs["app/jobs/jira/*"]:::background
        Mailers["app/mailers/jira/application_mailer.rb"]:::service
        Migrations["db/migrate/*"]:::db
        Gemspec["jira.gemspec & lib/jira/*.rb"]:::engine
        Rake["lib/tasks/jira_tasks.rake"]:::engine
    end

    %% User Interaction
    User["User"]:::user
    User -->|Visits /jira/*| Routes
    Routes -->|Mounts engine| EngineMount
    EngineMount --> Controllers
    Controllers -->|Render| Views
    Views -->|Serve assets| Manifest
    Controllers -->|Query| Models
    Controllers -->|Invoke| Services
    Controllers -->|Send emails| Mailers

    %% Services to External
    Services -->|REST/GraphQL calls| JiraAPI
    Services -->|GraphQL queries| CodeGiantAPI

    %% Background Jobs Flow
    Sidekiq --> Jobs
    Jobs -->|Use services| Services
    Jobs -->|Upsert data| Models
    Models --> DB

    %% Controllers read from DB
    Controllers -->|Read/write| DB

    %% External ↔ Models sync
    JiraAPI -->|Data| Models
    CodeGiantAPI -->|Data| Models

    %% Database migrations
    Migrations --> DB

    %% Initializers linking
    OmniAuthInit -.-> JiraAPI
    SidekiqInit -.-> Sidekiq
    AssetsInit -.-> Views

    %% Click Events
    click Routes "https://github.com/harminderbomrah/jira-engine/blob/master/config/routes.rb"
    click OmniAuthInit "https://github.com/harminderbomrah/jira-engine/blob/master/config/initializers/omniauth.rb"
    click SidekiqInit "https://github.com/harminderbomrah/jira-engine/blob/master/config/initializers/sidekiq.rb"
    click AssetsInit "https://github.com/harminderbomrah/jira-engine/blob/master/config/initializers/assets.rb"
    click Manifest "https://github.com/harminderbomrah/jira-engine/blob/master/app/assets/config/jira_manifest.js"
    click EngineMount "https://github.com/harminderbomrah/jira-engine/blob/master/lib/jira/engine.rb"
    click Controllers "https://github.com/harminderbomrah/jira-engine/blob/master/app/controllers/jira/application_controller.rb"
    click Controllers "https://github.com/harminderbomrah/jira-engine/blob/master/app/controllers/jira/pages_controller.rb"
    click Controllers "https://github.com/harminderbomrah/jira-engine/blob/master/app/controllers/jira/projects_controller.rb"
    click Controllers "https://github.com/harminderbomrah/jira-engine/blob/master/app/controllers/jira/field_mappings_controller.rb"
    click Controllers "https://github.com/harminderbomrah/jira-engine/blob/master/app/controllers/jira/sessions_controller.rb"
    click Views "https://github.com/harminderbomrah/jira-engine/blob/master/app/views/jira/pages/home.html.erb"
    click Views "https://github.com/harminderbomrah/jira-engine/blob/master/app/views/jira/pages/privacy.html.erb"
    click Views "https://github.com/harminderbomrah/jira-engine/blob/master/app/views/jira/shared/_alerts.html.erb"
    click Views "https://github.com/harminderbomrah/jira-engine/blob/master/app/views/layouts/jira/application.html.erb"
    click Views "https://github.com/harminderbomrah/jira-engine/blob/master/app/views/layouts/jira/mailer.html.erb"
    click Views "https://github.com/harminderbomrah/jira-engine/blob/master/app/views/layouts/jira/mailer.text.erb"
    click Helpers "https://github.com/harminderbomrah/jira-engine/blob/master/app/helpers/jira/application_helper.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/application_record.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/project.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/issue.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/comment.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/history.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/field_mapping.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/import_status.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/project_priority.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/project_status.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/project_type.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/user.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/jira_user.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/code_giant_user.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/user_mapping.rb"
    click Models "https://github.com/harminderbomrah/jira-engine/blob/master/app/models/jira/attachment.rb"
    click Services "https://github.com/harminderbomrah/jira-engine/blob/master/app/services/jira/jira_project_service.rb"
    click Services "https://github.com/harminderbomrah/jira-engine/blob/master/app/services/jira/jira_issue_service.rb"
    click Services "https://github.com/harminderbomrah/jira-engine/blob/master/app/services/jira/graphql_service.rb"
    click Services "https://github.com/harminderbomrah/jira-engine/blob/master/app/services/jira/graphql_mutation_service.rb"
    click Jobs "https://github.com/harminderbomrah/jira-engine/blob/master/app/jobs/jira/application_job.rb"
    click Jobs "https://github.com/harminderbomrah/jira-engine/blob/master/app/jobs/jira/fetch_jira_projects_job.rb"
    click Jobs "https://github.com/harminderbomrah/jira-engine/blob/master/app/jobs/jira/fetch_jira_issues_job.rb"
    click Jobs "https://github.com/harminderbomrah/jira-engine/blob/master/app/jobs/jira/fetch_codegiant_users_job.rb"
    click Jobs "https://github.com/harminderbomrah/jira-engine/blob/master/app/jobs/jira/update_issue_user_job.rb"
    click Mailers "https://github.com/harminderbomrah/jira-engine/blob/master/app/mailers/jira/application_mailer.rb"
    click Migrations "https://github.com/harminderbomrah/jira-engine/tree/master/db/migrate/"
    click Gemspec "https://github.com/harminderbomrah/jira-engine/blob/master/jira.gemspec"
    click Gemspec "https://github.com/harminderbomrah/jira-engine/blob/master/lib/jira/version.rb"
    click Rake "https://github.com/harminderbomrah/jira-engine/blob/master/lib/tasks/jira_tasks.rake"

    %% Styles
    classDef user fill:#cce5ff,stroke:#004085,color:#004085
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef background fill:#d4edda,stroke:#155724,color:#155724
    classDef db fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef engine fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef service fill:#ffeeba,stroke:#856404,color:#856404
```
