# bronco84/budget-planner-vue architecture

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

- Interactive diagram: https://gitdiagram.com/bronco84/budget-planner-vue
- Repository: https://github.com/bronco84/budget-planner-vue

## Overview

##### Project Type and Purpose
- This is a monolithic, full-stack web application built on Laravel (PHP) with an Inertia.js + Vue 3 frontend.
- Purpose: personal finance and budgeting tool that integrates with Plaid and other bank-feed strategies, manages budgets, transactions (including recurring), payoff plans, chat support, file attachments, and reporting.

##### Architectural Overview
- Pattern: MVC (Models, Views, Controllers) on the backend; component-based SPA on the frontend via Inertia.
- Single codebase: Laravel handles HTTP, CLI commands, background jobs, database migrations, and business logic (app/Services). Vue components render pages, talk to Laravel controllers over Inertia or AJAX fetch.

a. Client Layer
- Web Browser
- Inertia.js Adapter & Vue 3 SPA (resources/js)
b. Application Layer (Laravel)
- HTTP Controllers (app/Http/Controllers & subfolders)
- CLI/Console Commands (app/Console/Commands)
- Services & Business Logic (app/Services, Enums, Policies)
- Eloquent Models & Repositories (app/Models)
- Middleware (app/Http/Middleware)
- Request Validation (app/Http/Requests)
- Event Broadcasting / Notifications (EventServiceProvider)
c. Data Layer
- Relational Database (MySQL/PostgreSQL) via Eloquent
- Migrations & Seeders (database/migrations, database/seeders)
- Cache (Redis or file cache)
- Queue System (Redis/Database queue, jobs in database/jobs)
d. External Integrations
- Plaid API (app/Services/BankFeed/PlaidImportStrategy, PlaidController)
- Airtable Import Strategy (app/Services/BankFeed/AirtableImportStrategy)
- File Storage (local or S3 via config/filesystems)
- Optional third-party services: Mail (Mailgun, SMTP), Broadcasting (Pusher, Redis)
e. CLI & Scheduled Jobs
- Recurring transaction analysis
- Plaid account diagnosis/fixes
- Recurring transactions
- Laravel Scheduler (defined in app/Console/Kernel)

##### Relationships & Data Flows
- Browser → Inertia → Laravel HTTP Controller → Service Layer → Eloquent → Database
- Controllers ←→ Vue Components (page data & JSON) via Inertia endpoints
- CLI Commands / Scheduler → Service Layer → DB / External APIs
- Queue Workers consume jobs → Service Layer → DB / Notifications
- External API calls:
- PlaidImportStrategy ←→ Plaid API
- AirtableImportStrategy ←→ Airtable API
- File Uploads: Browser → Controller(FileController) → Storage → DB (FileAttachment)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Web Browser"]:::frontend
        SPA["Inertia.js & Vue 3 SPA"]:::frontend
    end

    Browser -->|"HTTP Request"| SPA
    SPA -->|"Inertia Endpoint"| BudgetController
    click SPA "https://github.com/bronco84/budget-planner-vue/tree/main/resources/js/"

    %% Application Layer
    subgraph "Application Layer" 
        direction TB

        %% Controllers
        subgraph Controllers
            direction TB
            BudgetController["BudgetController"]:::backend
            CalendarController["CalendarController"]:::backend
            CategoryController["CategoryController"]:::backend
            ChatController["ChatController"]:::backend
            FileController["FileController"]:::backend
            PayoffPlanController["PayoffPlanController"]:::backend
            PlaidController["PlaidController"]:::backend
            RecurringTransactionAnalysisController["RecurringTransactionAnalysisController"]:::backend
            RecurringTransactionController["RecurringTransactionController"]:::backend
            RecurringTransactionRuleController["RecurringTransactionRuleController"]:::backend
        end

        click Controllers "https://github.com/bronco84/budget-planner-vue/tree/main/app/Http/Controllers/"
        click BudgetController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/BudgetController.php"
        click CalendarController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/CalendarController.php"
        click CategoryController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/CategoryController.php"
        click ChatController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/ChatController.php"
        click FileController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/FileController.php"
        click PayoffPlanController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/PayoffPlanController.php"
        click PlaidController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/PlaidController.php"
        click RecurringTransactionAnalysisController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/RecurringTransactionAnalysisController.php"
        click RecurringTransactionController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/RecurringTransactionController.php"
        click RecurringTransactionRuleController "https://github.com/bronco84/budget-planner-vue/blob/main/app/Http/Controllers/RecurringTransactionRuleController.php"

        %% Middleware & Requests
        Middleware["Middleware"]:::backend
        click Middleware "https://github.com/bronco84/budget-planner-vue/tree/main/app/Http/Middleware/"
        Requests["Request Validation"]:::backend
        click Requests "https://github.com/bronco84/budget-planner-vue/tree/main/app/Http/Requests/"

        %% Services & Business Logic
        subgraph Services
            direction TB
            BankFeedService["BankFeedService"]:::backend
            BudgetService["BudgetService"]:::backend
            ChatService["ChatService"]:::backend
            FileService["FileService"]:::backend
            PayoffPlanService["PayoffPlanService"]:::backend
            PlaidService["PlaidService"]:::backend
            RecurringTransactionAnalysisService["RecurringTransactionAnalysisService"]:::backend
            RecurringTransactionService["RecurringTransactionService"]:::backend

            subgraph "Bank Feed Strategies"
                direction TB
                BankFeedImportInterface["BankFeedImportInterface"]:::backend
                PlaidImportStrategy["PlaidImportStrategy"]:::backend
                AirtableImportStrategy["AirtableImportStrategy"]:::backend
            end
        end
        click Services "https://github.com/bronco84/budget-planner-vue/tree/main/app/Services/"
        click BankFeedImportInterface "https://github.com/bronco84/budget-planner-vue/blob/main/app/Services/BankFeed/BankFeedImportInterface.php"
        click PlaidImportStrategy "https://github.com/bronco84/budget-planner-vue/blob/main/app/Services/BankFeed/PlaidImportStrategy.php"
        click AirtableImportStrategy "https://github.com/bronco84/budget-planner-vue/blob/main/app/Services/BankFeed/AirtableImportStrategy.php"

        %% Models & Repositories
        Models["Eloquent Models & Repositories"]:::backend
        click Models "https://github.com/bronco84/budget-planner-vue/tree/main/app/Models/"

        %% CLI & Scheduler
        subgraph "CLI & Scheduled Jobs"
            direction TB
            IdentifyRecurringTransactions["IdentifyRecurringTransactions"]:::backend
            DiagnosePlaidAccounts["DiagnosePlaidAccounts"]:::backend
            FixPlaidAccounts["FixPlaidAccounts"]:::backend
            Scheduler["Console Kernel (Scheduler)"]:::backend
        end
        click IdentifyRecurringTransactions "https://github.com/bronco84/budget-planner-vue/blob/main/app/Console/Commands/IdentifyRecurringTransactions.php"
        click DiagnosePlaidAccounts "https://github.com/bronco84/budget-planner-vue/blob/main/app/Console/Commands/DiagnosePlaidAccounts.php"
        click FixPlaidAccounts "https://github.com/bronco84/budget-planner-vue/blob/main/app/Console/Commands/FixPlaidAccounts.php"
        click Scheduler "https://github.com/bronco84/budget-planner-vue/blob/main/app/Console/Kernel.php"

        %% Event Broadcasting
        Events["EventServiceProvider"]:::backend
        click Events "https://github.com/bronco84/budget-planner-vue/blob/main/app/Providers/EventServiceProvider.php"

        %% Routes
        RoutesWeb["routes/web.php"]:::backend
        RoutesAPI["routes/api.php"]:::backend
        RoutesConsole["routes/console.php"]:::backend
        click RoutesWeb "https://github.com/bronco84/budget-planner-vue/blob/main/routes/web.php"
        click RoutesAPI "https://github.com/bronco84/budget-planner-vue/blob/main/routes/api.php"
        click RoutesConsole "https://github.com/bronco84/budget-planner-vue/blob/main/routes/console.php"
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Database[(Relational DB)]:::data
        Migrations["Migrations & Seeders"]:::data
        Cache[(Cache)]:::data
        Queue[(Queue System)]:::data
    end
    click Migrations "https://github.com/bronco84/budget-planner-vue/tree/main/database/migrations/"
    click Migrations "https://github.com/bronco84/budget-planner-vue/tree/main/database/seeders/"
    click Queue "https://github.com/bronco84/budget-planner-vue/blob/main/config/queue.php"

    %% External Integrations
    subgraph "External Services"
        direction TB
        PlaidAPI[("Plaid API")]:::external
        AirtableAPI[("Airtable API")]:::external
        Storage[("File Storage (S3/Local)")]:::external
        Mail[("Mail Services")]:::external
        Broadcasting[("Broadcasting Services")]:::external
    end

    %% Relationships
    SPA -->|"Inertia Request"| BudgetController
    BudgetController -->|"invoke"| BudgetService
    BudgetService -->|"Eloquent ORM"| Models
    Models -->|"persist/read"| Database

    Controllers --> Middleware
    Controllers --> Requests
    Controllers --> Events

    BankFeedService -->|implements| BankFeedImportInterface
    BankFeedImportInterface -->|uses| PlaidImportStrategy
    BankFeedImportInterface -->|uses| AirtableImportStrategy
    PlaidImportStrategy -->|"HTTP"| PlaidAPI
    AirtableImportStrategy -->|"HTTP"| AirtableAPI

    FileController -->|"store"| Storage
    FileService -->|"persist metadata"| Database

    IdentifyRecurringTransactions -->|"calls"| RecurringTransactionAnalysisService
    Scheduler -->|"schedules"| IdentifyRecurringTransactions
    IdentifyRecurringTransactions -->|"persist results"| Database

    %% Queue flows
    RecurringTransactionAnalysisService -->|"queue job"| Queue
    Queue -.->|"worker consumes"| RecurringTransactionService
    RecurringTransactionService -->|"update"| Database
    RecurringTransactionService -->|"broadcast"| Broadcasting

    %% Cache usage
    Services -->|"cache"| Cache

    %% Event-based chat
    ChatController -->|"delegate"| ChatService
    ChatService -->|"store messages"| Database
    ChatService -->|"broadcast"| Broadcasting

    %% File uploads
    SPA -->|"AJAX Upload"| FileController
    FileController -->|"save file"| Storage
    FileController -->|"record"| Database

    %% CLI integrations
    DiagnosePlaidAccounts -->|"uses"| PlaidService
    FixPlaidAccounts -->|"uses"| PlaidService

    %% Class Definitions
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#E5F9E0,stroke:#1AAB2B,color:#1AAB2B;
    classDef data fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#EADFF8,stroke:#8E44AD,color:#8E44AD;
```
