# benefactorum/app architecture

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

- Interactive diagram: https://gitdiagram.com/benefactorum/app
- Repository: https://github.com/benefactorum/app

## Overview

Based on your project’s file tree and README, Benefactorum is a full-stack non-profit donation platform designed to let French donors discover and support causes they care about. Its tech stack comprises a Ruby on Rails backend (with SQLite as the database) and a React with TypeScript frontend, bridged by Inertia.js for SSR capabilities. It also uses TailwindCSS and shadcn/ui for styling, and modern build/deployment tooling (Vite, Kamal, GitHub Actions, and dev containers).

##### Main Components
- Frontend Client: Represent the React with TypeScript application.
- Use of Inertia.js for handling server-side rendering and bridging with Rails.
- Role of assets, shared UI components (including those from shadcn/ui), hooks, and pages.
- Backend API: Capture the Ruby on Rails application.
- Controllers (including auth-related and resource-specific ones such as Contributions, Osbl, Users, etc.), models, serializers, jobs, mailers, and services.
- Architectural patterns like MVC and service objects (for contribution and osbl import logic).
- Database: Include the SQLite database and any replication features (Litestream).
- External Integrations:
- Deployment: Kamal hooks, Docker setup (from both the root Dockerfile and the .devcontainer folder), GitHub Actions workflows for CI/CD.
- APIs/External Services: Note any integration modules (e.g., GitHub API, French Address API) visible under the lib folder.
- Additional Components:
- Asynchronous processing: Jobs that handle tasks like osbl_import processing and creation.
- Testing environment: Separate test directories for frontend and backend testing (RSpec, system tests, etc.).
- DevOps and Containerization: Dev container configuration along with Docker-related files.
- Static assets and public files: Represent the public folder contents (error pages, robots.txt, and assets like PDFs).

##### Relationships and Interactions
- API calls and data flows that occur between these layers.
- Backend Internal Flows:
- How Rails controllers interact with models and services.
- Detail asynchronous workflows (jobs processing and external API interactions).
- Mailers for notifications.
- Data Storage:
- Rails backend to the SQLite database.
- Optionally detail migration flows for setting up and updating data schemas.
- CI/CD Pipeline & DevOps:
- Build processes like Vite bundling for frontend assets and containerization steps.
- External APIs:
- Link from the services (and lib modules) to external APIs (e.g., GitHub, Firecrawl, or French Address API).

##### Architectural Patterns and Design Principles
- That the backend uses Rails’ MVC pattern, supplemented with service objects and background jobs.
- The frontend leverages component-based architecture with a clear separation between layout, pages, and shared UI components.
- Separation of concerns between the development environment (containerized setup), build pipeline (using Vite and GitHub Actions), and production deployment.
- Use of Dependency Injection – for example, the use of hooks and context in React, as well as decoupled services in Rails.

##### Technologies, Frameworks, and Libraries
- Ruby on Rails 8 for Backend.
- SQLite (and Litestream replication if relevant) for the database.
- React with TypeScript, Inertia.js, TailwindCSS, and shadcn/ui for the frontend.
- Vite for asset bundling.
- Kamal for deployment.
- Containerization using Docker and Dev Containers.
- CI/CD with GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user
    User -->|"uses"| FE["React Frontend (Inertia.js)"]:::frontend

    subgraph "Frontend Layer"
        FE
        A["Assets"]:::frontendDetail
        CP["UI Components"]:::frontendDetail
        EN["Entrypoints"]:::frontendDetail
        HK["Hooks"]:::frontendDetail
        UT["Utilities"]:::frontendDetail

        FE --> A
        FE --> CP
        FE --> EN
        FE --> HK
        FE --> UT
    end

    subgraph "Backend Layer"
        RC["Rails Controllers"]:::backend
        MD["Models"]:::backend
        SE["Serializers"]:::backend
        SV["Service Objects"]:::backend
        JB["Background Jobs"]:::backend
        ML["Mailers"]:::backend
        EA["External APIs"]:::backendExternal

        RC --> MD
        RC --> SE
        RC --> SV
        RC --> JB
        RC --> ML
        SV -->|"calls"| EA
        JB -->|"triggers"| EA
    end

    subgraph "Data Layer"
        DB(("SQLite Database")):::database
        MD --> DB
    end

    subgraph "External Integrations & DevOps"
        DP["Deployment (Kamal hooks)"]:::external
        DC["Dev Containers & Docker"]:::external
        GH["CI/CD (GitHub Actions)"]:::external

        DP --- DC
        DP --- GH
    end

    subgraph "Additional Components"
        TE["Testing Environment"]:::testing
        PF["Public Files"]:::public
    end

    %% Connections between layers
    FE -->|"HTTP_requests"| RC
    GH --- FE
    GH --- RC
    DC --- FE
    DC --- RC
    DP --- FE
    DP --- RC
    TE --- FE
    TE --- RC
    FE -->|"static_assets"| PF

    %% Click Events for Frontend
    click FE "https://github.com/benefactorum/app/tree/main/app/frontend"
    click A "https://github.com/benefactorum/app/tree/main/app/frontend/assets"
    click CP "https://github.com/benefactorum/app/tree/main/app/frontend/components"
    click EN "https://github.com/benefactorum/app/tree/main/app/frontend/entrypoints"
    click HK "https://github.com/benefactorum/app/tree/main/app/frontend/hooks"
    click UT "https://github.com/benefactorum/app/tree/main/app/frontend/lib"

    %% Click Events for Backend
    click RC "https://github.com/benefactorum/app/tree/main/app/controllers"
    click MD "https://github.com/benefactorum/app/tree/main/app/models"
    click SE "https://github.com/benefactorum/app/tree/main/app/serializers"
    click SV "https://github.com/benefactorum/app/tree/main/app/services"
    click JB "https://github.com/benefactorum/app/tree/main/app/jobs"
    click ML "https://github.com/benefactorum/app/tree/main/app/mailers"

    %% Click Event for Database
    click DB "https://github.com/benefactorum/app/tree/main/db"

    %% Click Events for External Integrations & DevOps
    click DP "https://github.com/benefactorum/app/tree/main/.kamal/hooks"
    click DC "https://github.com/benefactorum/app/blob/main/.devcontainer"
    click GH "https://github.com/benefactorum/app/tree/main/.github/workflows"

    %% Click Event for External API Integrations
    click EA "https://github.com/benefactorum/app/tree/main/lib"

    %% Click Event for Additional Components
    click TE "https://github.com/benefactorum/app/tree/main/spec"
    click PF "https://github.com/benefactorum/app/tree/main/public"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px,color:#000;
    classDef frontendDetail fill:#BFEFFF,stroke:#000,stroke-width:2px,color:#000;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px,color:#000;
    classDef backendExternal fill:#98FB98,stroke:#000,stroke-width:2px,color:#000;
    classDef database fill:#D3D3D3,stroke:#000,stroke-width:2px,color:#000;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px,color:#000;
    classDef testing fill:#FFD700,stroke:#000,stroke-width:2px,color:#000;
    classDef public fill:#FFFACD,stroke:#000,stroke-width:2px,color:#000;
    classDef user fill:#FFE4B5,stroke:#000,stroke-width:2px,color:#000;
```
