# nucleus-jena/tomsy architecture

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

- Interactive diagram: https://gitdiagram.com/nucleus-jena/tomsy
- Repository: https://github.com/nucleus-jena/tomsy

## Overview

##### Main Components
- Frontend Client: Represent the parts served to the end user. This includes the browser where the Vue.js components, pages, and related assets (all within app/javascript and app/assets) render the user interface.
- API Layer & Controllers: The Rails “controller” layer (especially the API controllers found under app/controllers/api) represents the service endpoints that handle RESTful requests and responses.
- Business Logic & Models: The Rails models (in app/models) hold the business semantics including process definitions, workflows, user management, and notifications.
- Real-time Communication: Action Cable channels (in app/channels) that enable live updates (e.g., for notifications or activity hubs).
- Workflow Engine Integration: External BPMN files (in the workflow folder) and initializers (like camunda.rb) indicate integration with Camunda for workflow management.
- Supporting Services and Libraries: This includes the authentication system (indirectly via Devise by the related views and controllers), external integrations through ElasticSearch (see config/initializers/elastic_search.rb), and error tracking (Sentry via sentry_raven.rb).

##### Out Interactions and Relationships
- Rails Backend’s internal flow: Controllers call business logic (services and interactors) and then interact with Models that communicate with the Database.
- That the Backend also leverages Action Cable connections for real-time updates back to the frontend.
- Demonstrate that the workflow subsystem (Camunda integration) feeds into the business logic via JSON/BPMN message exchanges or internal service calls.
- Optionally, include external services (like ElasticSearch, Tika for document handling, and Sentry for error monitoring) as ancillary components directly interfacing with the backend.

##### Important Architectural Patterns & Design Principles
- MVC Pattern: Illustrate clear separations between Views (Vue.js and Haml templates in app/views), Controllers (Rails controllers handling API requests), and Models (domain logic).
- Component-based Frontend: Note that the frontend uses a modular Vue.js structure (with components, controls, mixins, pages, and routing) ensuring flexibility.
- Service Integration: Emphasize the use of background jobs (see app/jobs) for asynchronous tasks like reindexing, workflow handling, and notifications.
- Modular Workflows: The workflow BPMN definitions signal that process management is abstracted into separate, maintainable workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    UserBrowser("User Browser"):::frontend
    subgraph "Frontend Layer"
        VueComponents("Vue.js Components, Pages & Router"):::frontend
        FrontAssets("Additional Frontend Assets"):::frontend
    end
    UserBrowser -->|"HTTP/S"| VueComponents
    VueComponents -->|"AJAX_calls"| RailsAPI

    %% Backend API and Business Logic
    subgraph "Backend Layer"
        RailsAPI("Rails API Endpoints (Controllers)"):::backend
        BusinessLogic("Business Logic & Models"):::backend
        Database("Database (ActiveRecord/SQL)"):::backend
        RealTime("Real-time Communication (Action Cable)"):::backend
        
        RailsAPI -->|"calls"| BusinessLogic
        BusinessLogic -->|"CRUD"| Database
        RailsAPI -->|"push_updates"| RealTime
    end

    %% Workflow Engine Integration
    subgraph "Workflow Engine Integration"
        Camunda("Camunda Integration (Initializer)"):::backend
        BPMN("BPMN Definitions"):::backend
    end
    BusinessLogic -->|"workflow_calls"| Camunda
    BusinessLogic -->|"workflow_calls"| BPMN

    %% External Services Integration
    subgraph "External Services"
        Auth("Authentication (Devise)"):::external
        ES("ElasticSearch Integration"):::external
        Sentry("Error Tracking (Sentry)"):::external
        Tika("Document Handling (Tika)"):::external
    end
    RailsAPI -->|"integrates"| Auth
    RailsAPI -->|"integrates"| ES
    RailsAPI -->|"integrates"| Sentry
    RailsAPI -->|"integrates"| Tika

    %% Real-time update flow back to Frontend
    RealTime -->|"push_updates"| VueComponents

    %% Click Events
    click VueComponents "https://github.com/nucleus-jena/tomsy/tree/main/app/javascript"
    click FrontAssets "https://github.com/nucleus-jena/tomsy/tree/main/app/assets"
    click RailsAPI "https://github.com/nucleus-jena/tomsy/tree/main/app/controllers/api"
    click BusinessLogic "https://github.com/nucleus-jena/tomsy/tree/main/app/models"
    click RealTime "https://github.com/nucleus-jena/tomsy/tree/main/app/channels"
    click BPMN "https://github.com/nucleus-jena/tomsy/tree/main/workflow"
    click Camunda "https://github.com/nucleus-jena/tomsy/blob/main/config/initializers/camunda.rb"
    click Auth "https://github.com/nucleus-jena/tomsy/tree/main/app/views/devise"
    click ES "https://github.com/nucleus-jena/tomsy/blob/main/config/initializers/elastic_search.rb"
    click Sentry "https://github.com/nucleus-jena/tomsy/blob/main/config/initializers/sentry_raven.rb"
    click Tika "https://github.com/nucleus-jena/tomsy/blob/main/config/initializers/tika.rb"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
