# murdho/spendbetter architecture

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

- Interactive diagram: https://gitdiagram.com/murdho/spendbetter
- Repository: https://github.com/murdho/spendbetter

## Overview

##### Main System Components

A. Frontend Layer:
- Rails views structure (/app/views)
- JavaScript components (Stimulus controllers in /app/javascript/controllers)
- PWA capabilities (manifest.json and service-worker.js)

B. Application Layer:
- Controllers (entries_controller.rb, folders_controller.rb)
- Models with special emphasis on the Bank namespace hierarchy
- Background Jobs system (indicated by /app/jobs)

C. Banking Integration Layer:
- Bank models (/app/models/bank/*)
- HTTP handling with token refresh mechanism
- Institution and Account management

D. Data Layer:
- Database (indicated by schema.rb and migrations)
- Token management system
- Cache system (cache.yml)

##### Component Relationships

**User Interface ↔ Controllers ↔ Models ↔ Banking Integration ↔ External Banking APIs**
- ↕
- Background Jobs
- ↕
- Database/Cache

##### Specific Implementation Details

Technical elements:

a) Authentication Flow:
- Token management system (Token model)
- Auto-refresh mechanism (bank/http/token_auto_refresh.rb)

b) Data Organization:
- Folder structure (Folder model)
- Entries management (Entry model)
- Banking data models (Account, Connection, Institution)

c) API Integration:
- HTTP client implementation (bank/http/jason.rb)
- Banking institution connections

##### Infrastructure Components

Deployment-related elements:

- Docker container (Dockerfile present)
- Kamal deployment configuration
- Background job processing
- Caching layer

##### Key Architectural Patterns to Highlight

- MVC pattern (Rails standard)
- Service-oriented architecture for banking integration
- Background job processing architecture
- Token-based authentication system
- PWA capabilities

##### Technical Stack Indicators

Technologies:

- Ruby on Rails
- Stimulus.js
- PostgreSQL (implied by Rails setup)
- Docker
- PWA
- Background Job Processing
- Caching System

This architecture appears to be designed for scalability and security, which should be emphasized in the visual representation through clear separation of concerns and well-defined boundaries between components.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI["User Interface Layer"]
        Views["Views"]:::frontend
        JS["JavaScript Components"]:::frontend
        PWA["PWA Implementation"]:::frontend
    end

    subgraph AL["Application Layer"]
        EC["Entries Controller"]:::controller
        FC["Folders Controller"]:::controller
        BJ["Background Jobs"]:::service
        EM["Entry Model"]:::model
        FM["Folder Model"]:::model
    end

    subgraph BIL["Banking Integration Layer"]
        BM["Bank Models"]:::model
        HC["HTTP Client"]:::service
        TR["Token Refresh"]:::security
        IM["Institution Management"]:::service
        AM["Account Management"]:::service
        CH["Connection Handler"]:::service
    end

    subgraph DL["Data Layer"]
        DB[(Database)]:::database
        TM["Token Model"]:::model
        Cache[(Cache)]:::cache
    end

    subgraph INF["Infrastructure"]
        Docker["Docker"]:::infra
        Deploy["Deployment Config"]:::infra
        BJC["Background Job Config"]:::infra
        AppConfig["Application Config"]:::infra
    end

    Views --> EC & FC
    JS --> Views
    PWA --> Views
    EC & FC --> EM & FM
    EM & FM --> BM
    BM --> HC
    HC --> TR
    TR --> TM
    HC --> IM & AM & CH
    BJ --> DB
    IM & AM & CH --> DB
    EC & FC --> Cache
    
    %% Click Events
    click Views "https://github.com/murdho/spendbetter/tree/main/app/views/"
    click JS "https://github.com/murdho/spendbetter/tree/main/app/javascript/controllers/"
    click PWA "https://github.com/murdho/spendbetter/tree/main/app/views/pwa/"
    click EC "https://github.com/murdho/spendbetter/blob/main/app/controllers/entries_controller.rb"
    click FC "https://github.com/murdho/spendbetter/blob/main/app/controllers/folders_controller.rb"
    click BJ "https://github.com/murdho/spendbetter/tree/main/app/jobs/"
    click EM "https://github.com/murdho/spendbetter/blob/main/app/models/entry.rb"
    click FM "https://github.com/murdho/spendbetter/blob/main/app/models/folder.rb"
    click BM "https://github.com/murdho/spendbetter/tree/main/app/models/bank/"
    click HC "https://github.com/murdho/spendbetter/blob/main/app/models/bank/http/jason.rb"
    click TR "https://github.com/murdho/spendbetter/blob/main/app/models/bank/http/token_auto_refresh.rb"
    click IM "https://github.com/murdho/spendbetter/blob/main/app/models/bank/institution.rb"
    click AM "https://github.com/murdho/spendbetter/blob/main/app/models/bank/account.rb"
    click CH "https://github.com/murdho/spendbetter/blob/main/app/models/bank/connection.rb"
    click TM "https://github.com/murdho/spendbetter/blob/main/app/models/token.rb"
    click Docker "https://github.com/murdho/spendbetter/tree/main/Dockerfile"
    click Deploy "https://github.com/murdho/spendbetter/blob/main/config/deploy.yml"
    click BJC "https://github.com/murdho/spendbetter/blob/main/config/queue.yml"
    click AppConfig "https://github.com/murdho/spendbetter/blob/main/config/spendbetter.yml"

    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef controller fill:#2ecc71,stroke:#27ae60,color:white
    classDef model fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef service fill:#e67e22,stroke:#d35400,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,color:white
    classDef database fill:#34495e,stroke:#2c3e50,color:white
    classDef cache fill:#9b59b6,stroke:#8e44ad,color:white
    classDef infra fill:#1abc9c,stroke:#16a085,color:white

    %% Legend
    subgraph Legend
        F["Frontend"]:::frontend
        C["Controller"]:::controller
        M["Model"]:::model
        S["Service"]:::service
        SEC["Security"]:::security
        D[(Database)]:::database
        CA[(Cache)]:::cache
        I["Infrastructure"]:::infra
    end
```
