# emcousin/pkp architecture

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

- Interactive diagram: https://gitdiagram.com/emcousin/pkp
- Repository: https://github.com/emcousin/pkp

## Overview

##### Main Components
- Rails Application (Backend): This is the core where all business logic and MVC responsibilities reside. Break this down into:
- Controllers: There are several namespaced controllers (admin, coach, dashboard, contacts, etc.) that represent different areas of the back-office interface.
- Models: The data models (e.g., user, member, subscription, course, contact) are implemented along with various concerns (extensions for devise, subscriptions, members, courses, etc.) to encapsulate business rules.
- Views: Organized by theme (admin, dashboard, devise, etc.) to generate the rendered pages.
- Services: For example, the single service “pdf_generator.rb” and other business logic that is separated outside of controllers or models.
- Channels: WebSocket channels (in app/channels) which indicate that realtime features may be supported (e.g., for live notifications or updates).
- Jobs: Background processing via job classes (notably the stripe jobs and more) that likely work with Sidekiq as indicated by the initializer and config files.
- Mailers and Mailboxes: For email notifications, confirmations, and related functionality.
- Database: Indicated by the presence of PostgreSQL configuration and migration files which form the persistent store for the data models.
- External Dependencies and Integrations:
- Redis – as seen in the prerequisites and initializer.
- Stripe – there are several initializers and jobs that manage customers, charges and subscriptions.
- Third-party libraries for background processing (Sidekiq, observed in config/initializers/sidekiq.rb and config/sidekiq.yml).
- Other external assets and tooling including Yarn, Node, and Foreman for managing multiple processes.

##### Relationships and Interactions
- A typical data flow starts at the browser client which hits the Rails controllers, triggering the MVC cycle (Controllers accept requests, interact with Models, and render Views).
- Background jobs (through Sidekiq) perform asynchronous tasks, like payment processing or notifications.
- The mailers generate emails for various transactions (confirmation, subscription updates, etc.) which are then delivered to users.
- Channels (using Action Cable) maintain bi-directional communication for realtime updates.
- External services (such as Stripe) are integrated via dedicated jobs and initializers, so show how the Rails app communicates with these systems.
- Caching or session management could also be highlighted if needed (through Redis).

##### Architectural Patterns and Design Principles
- MVC Pattern: The Rails framework’s core design separates the application logic into Models, Views, and Controllers.
- Namespacing: Different folders under controllers (admin, dashboard, coach, contacts) suggest clear segmentation according to user roles or functionality.
- Service Layer: Business logic separated into services (e.g., PDF generation) promoting a clean separation from controller logic.
- Background Processing: Use of job classes (and Sidekiq) for heavy or asynchronous tasks to keep the request/response cycle fast.
- Use of Concerns: Both models and controllers use concerns to share common behavior, which is an important design pattern in this Rails codebase.

##### Relevant Technologies & Frameworks
- Ruby on Rails – as the main web framework.
- PostgreSQL – for the database.
- Redis – for caching and as a data store for background job processing.
- Sidekiq – for handling background jobs.
- Stripe – for payment processing.
- Action Cable – for websockets and realtime features.
- Devise – for authentication (based on the configurations and overridden controller concerns).
- Webpack/Yarn – for handling JavaScript assets.
- Tailwind CSS – for styling (as indicated by application.tailwind.css).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser: Web Client"]:::client
        AssetsStyles["Stylesheets"]:::client
        AssetsImages["Images"]:::client
        AssetsJS["JS Controllers"]:::client
    end

    %% Rails Application
    subgraph "Rails Application"
        subgraph "Controllers"
            AdminControllers["Admin Controllers"]:::rails
            CoachControllers["Coach Controllers"]:::rails
            DashboardControllers["Dashboard Controllers"]:::rails
            ContactsControllers["Contacts Controllers"]:::rails
            PWAControllers["PWA Controllers"]:::rails
            GeneralControllers["General Controllers"]:::rails
        end
        subgraph "Models"
            DataModels["Data Models"]:::rails
            ModelConcerns["Model Concerns"]:::rails
        end
        subgraph "Views & Templates"
            RailsViews["Rails Views"]:::rails
        end
        subgraph "Services"
            PDFService["PDF Generator"]:::rails
        end
        subgraph "Channels"
            WebSocketChannels["WebSocket Channels"]:::rails
        end
        subgraph "Jobs"
            Jobs["Background Jobs"]:::rails
            StripeJobs["Stripe Jobs"]:::rails
        end
        subgraph "Mailers"
            Mailers["Mailers"]:::rails
            Mailboxes["Mailboxes"]:::rails
        end
    end

    %% External Services & Integrations
    subgraph "External Services & Integrations"
        DatabaseNode["PostgreSQL Database"]:::external
        RedisNode["Redis Server"]:::external
        SidekiqInit["Sidekiq Init"]:::external
        SidekiqConfig["Sidekiq Config"]:::external
        StripeInit["Stripe API"]:::external
        ExternalTools["External Tools"]:::external
    end

    %% Data Flow Connections
    Browser -->|"loads"| AssetsStyles
    Browser -->|"loads"| AssetsImages
    Browser -->|"loads"| AssetsJS
    AssetsJS -->|"bundled_by"| ExternalTools

    Browser -->|"HTTP_Request"| GeneralControllers

    %% Controllers interactions
    GeneralControllers -->|"CRUD"| DataModels
    GeneralControllers -->|"renders"| RailsViews
    GeneralControllers -->|"triggers"| PDFService
    GeneralControllers -->|"notifies"| Mailers
    GeneralControllers -->|"schedules"| Jobs
    GeneralControllers -->|"realtime"| WebSocketChannels

    %% Additional controllers (namespaced)
    AdminControllers -->|"CRUD"| DataModels
    CoachControllers -->|"CRUD"| DataModels
    DashboardControllers -->|"renders"| RailsViews
    ContactsControllers -->|"handles"| DataModels
    PWAControllers -->|"manages"| RailsViews

    %% Models interactions with Database
    DataModels -->|"queries"| DatabaseNode

    %% Jobs interactions
    Jobs -->|"async_processing"| SidekiqInit
    Jobs -->|"async_processing"| SidekiqConfig
    StripeJobs -->|"calls"| StripeInit

    %% Caching and Sessions
    GeneralControllers ---|"cache"| RedisNode

    %% Styles
    classDef client fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef rails fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px;

    %% Click Events for Client Layer
    click AssetsStyles "https://github.com/emcousin/pkp/tree/master/app/assets/stylesheets"
    click AssetsImages "https://github.com/emcousin/pkp/tree/master/app/assets/images"
    click AssetsJS "https://github.com/emcousin/pkp/tree/master/app/javascript/controllers"

    %% Click Events for Rails Controllers
    click AdminControllers "https://github.com/emcousin/pkp/tree/master/app/controllers/admin"
    click CoachControllers "https://github.com/emcousin/pkp/tree/master/app/controllers/coach"
    click DashboardControllers "https://github.com/emcousin/pkp/tree/master/app/controllers/dashboard"
    click ContactsControllers "https://github.com/emcousin/pkp/tree/master/app/controllers/contacts"
    click PWAControllers "https://github.com/emcousin/pkp/tree/master/app/controllers/pwa"
    click GeneralControllers "https://github.com/emcousin/pkp/blob/master/app/controllers/application_controller.rb"

    %% Click Events for Models
    click DataModels "https://github.com/emcousin/pkp/tree/master/app/models"
    click ModelConcerns "https://github.com/emcousin/pkp/tree/master/app/models/concerns"

    %% Click Event for Views
    click RailsViews "https://github.com/emcousin/pkp/tree/master/app/views"

    %% Click Event for Services
    click PDFService "https://github.com/emcousin/pkp/blob/master/app/services/pdf_generator.rb"

    %% Click Event for Channels
    click WebSocketChannels "https://github.com/emcousin/pkp/tree/master/app/channels/application_cable"

    %% Click Events for Jobs
    click Jobs "https://github.com/emcousin/pkp/tree/master/app/jobs"
    click StripeJobs "https://github.com/emcousin/pkp/tree/master/app/jobs/stripe"

    %% Click Events for Mailers and Mailboxes
    click Mailers "https://github.com/emcousin/pkp/tree/master/app/mailers"
    click Mailboxes "https://github.com/emcousin/pkp/tree/master/app/mailboxes"

    %% Click Events for External Services
    click DatabaseNode "https://github.com/emcousin/pkp/blob/master/config/database.yml"
    click RedisNode "https://github.com/emcousin/pkp/blob/master/config/initializers/redis.rb"
    click SidekiqInit "https://github.com/emcousin/pkp/blob/master/config/initializers/sidekiq.rb"
    click SidekiqConfig "https://github.com/emcousin/pkp/blob/master/config/sidekiq.yml"
    click StripeInit "https://github.com/emcousin/pkp/blob/master/config/initializers/stripe.rb"
    click ExternalTools "https://github.com/emcousin/pkp/blob/master/package.json"
```
