# alexsantosfilho/desafio-dev architecture

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

- Interactive diagram: https://gitdiagram.com/alexsantosfilho/desafio-dev
- Repository: https://github.com/alexsantosfilho/desafio-dev

## Overview

##### Project Overview & Main Concern
- Project Type: This is a full-stack Ruby on Rails web application designed to process CNAB files—parsing, normalizing, and storing financial transaction data—and then display transactions by store along with account balances.
- Key Purpose: Facilitate file uploads (via a web form), parse the uploaded CNAB file, store the parsed data in a relational (PostgreSQL) database, and provide both a web UI and RESTful API (documented with Swagger via Rswag) to expose the functionality.
- Auxiliary Components: It also includes usage of Solid Cache, Solid Queue, and Solid Cable to manage caching, background jobs, and real-time communication respectively, as well as OAuth for authentication (and a simple sessions system) and overcommit for Git hook validations.

##### Analyzing the File Structure
- The project follows a standard Rails MVC structure with directories such as:
– app/controllers, app/models, app/views, and app/services where the core business logic occurs.
– app/javascript and app/assets for frontend assets and interactivity (leveraging Hotwire and Turbo).
– config for environment configuration, routes, database connections, and initializer scripts.
- There’s a dedicated directory structure for jobs, mailers, channels, and repositories as well, indicating clear separation of concerns.
- The inclusion of Dockerfile, docker-compose.yml, and various Git hook configurations (Overcommit, Kamal hooks) highlight that deployment and code quality checks are an integral part of the project.

a. Frontend Layer
– Web Interface: Views rendered from app/views (and assets in app/assets and JavaScript controllers in app/javascript) to provide the UI for file upload, transaction listings, dashboard, and login pages.
– API Documentation: Swagger UI (served at /api-docs) which leverages Rswag.
b. Backend Application Layer
– Controllers (e.g., SessionsController, TransactionsController, Api::V1::CnabController): Responsible for handling HTTP requests, initiating file upload processing, authentication (including OAuth callbacks) and API requests.
– Services: CNAB parsing logic (CnabParserService), transaction importing logic (Transactions import service), and store balance updater that encapsulates business logic.
– Jobs: Background processing through Solid Queue jobs for tasks like processing transactions asynchronously.
c. Database Layer
– PostgreSQL database holds the primary data models (Stores, Transactions, Users, Sessions).
d. External & Auxiliary Services
– External Authentication via OAuth (for Google, etc.)
– Real-time updates with Solid Cable (for live updates using Turbo Streams)
– Caching with Solid Cache and background job processing with Solid Queue
– Git hooks & code quality tools (Overcommit) and Docker for development and deployment.

##### Relationships, Data Flow & Architectural Patterns
- Clear separation of concerns (MVC) where incoming requests from the client (uploading a CNAB file or triggering an API call) flow from the frontend (via controllers) to the services that parse the file and update the models, which in turn interact with the PostgreSQL database.
- Database relationships (Store – Transaction and User – Session) and the REST API endpoints with proper versioning.
- Additional layers for Docker encapsulation (container boundaries) and external integrations (OAuth providers) should be highlighted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE_Upload["File Upload UI"]:::frontend
        FE_Docs["API Docs (Swagger)"]:::frontend
        Views["Views"]:::frontend
        Assets["Assets"]:::frontend
        JSCont["JS Controllers"]:::frontend
        RswagUI["Rswag UI"]:::frontend
        RswagApi["Rswag API Initializer"]:::frontend
        RswagUIInit["Rswag UI Initializer"]:::frontend
        SwaggerSpec["Swagger Spec"]:::frontend
    end

    %% Backend Application Layer
    subgraph "Backend Application Layer"
        CTRPrimary["Primary Controllers"]:::backend
        CTRAPI["API Controllers"]:::backend
        subgraph "Services"
            S1["CNAB Parser Service"]:::backend
            S2["CNAB Importer"]:::backend
            S3["Transactions Import Service"]:::backend
            S4["Store Balance Updater"]:::backend
        end
        Jobs["Import Job (Solid Queue)"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        Models["Models (ActiveRecord)"]:::database
        DBConfig["DB Config & Migrations"]:::database
    end

    %% External Services
    subgraph "External Services"
        Auth["Authentication (OAuth)"]:::external
        Channels["Real-Time Channels"]:::external
        JSChannels["JS Channels"]:::external
        Cache["Caching (Solid Cache)"]:::external
        Queue["Background Queue (Solid Queue)"]:::external
    end

    %% Deployment & Development Tools
    subgraph "Deployment & Dev Tools"
        Dockerfile["Dockerfile"]:::deployment
        DockerCompose["Docker Compose"]:::deployment
        GitHooks["Git Hooks"]:::deployment
        Overcommit["Overcommit Config"]:::deployment
    end

    %% Connections - Frontend
    User -->|"access"| FE_Upload
    User -->|"view-docs"| FE_Docs
    FE_Upload -->|"renders"| Views
    FE_Upload -->|"loads"| Assets
    FE_Upload -->|"activates"| JSCont
    FE_Docs -->|"displays"| RswagUI
    RswagUI --> RswagApi
    RswagUI --> RswagUIInit
    RswagUI --> SwaggerSpec

    %% Connections - Frontend to Backend
    FE_Upload -->|"submits-file"| CTRPrimary
    FE_Docs -->|"API-request"| CTRAPI

    %% Connections - Backend Processing
    CTRPrimary -->|"triggers"| S1
    CTRPrimary -->|"triggers"| S2
    CTRPrimary -->|"triggers"| S3
    CTRPrimary -->|"triggers"| S4
    CTRPrimary -->|"authenticates"| Auth
    CTRAPI -->|"handles-API"| S1
    CTRAPI -->|"handles-API"| S2
    CTRAPI -->|"handles-API"| S3
    CTRAPI -->|"handles-API"| S4
    S1 -->|"persists-data"| Models
    S2 -->|"persists-data"| Models
    S3 -->|"persists-data"| Models
    S4 -->|"updates-balances"| Models
    CTRPrimary -->|"delegates-job"| Jobs
    Jobs -->|"enqueues-task"| Queue
    Queue -->|"notifies-async"| Channels
    Jobs -->|"notifies-async"| Channels

    %% Connections - Database
    Models -->|"configured-by"| DBConfig

    %% Deployment Connections
    CTRPrimary -->|"runs-in"| Dockerfile
    CTRAPI -->|"runs-in"| Dockerfile
    Dockerfile -->|"orchestrated-by"| DockerCompose
    DockerCompose -->|"enforced-by"| GitHooks
    GitHooks --> Overcommit

    %% Classes and Styling
    classDef frontend fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef backend fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef database fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef external fill:#e6e6e6,stroke:#666666,stroke-width:2px;
    classDef deployment fill:#ccffcc,stroke:#006600,stroke-width:2px;

    %% Click Events - Frontend
    click Views "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/views"
    click Assets "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/assets"
    click JSCont "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/javascript/controllers"
    click RswagUI "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/views/rswag/ui"
    click RswagApi "https://github.com/alexsantosfilho/desafio-dev/blob/main/config/initializers/rswag_api.rb"
    click RswagUIInit "https://github.com/alexsantosfilho/desafio-dev/blob/main/config/initializers/rswag_ui.rb"
    click SwaggerSpec "https://github.com/alexsantosfilho/desafio-dev/blob/main/swagger/v1/swagger.yaml"

    %% Click Events - Backend Controllers
    click CTRPrimary "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/controllers"
    click CTRAPI "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/controllers/api/v1"

    %% Click Events - Services
    click S1 "https://github.com/alexsantosfilho/desafio-dev/blob/main/app/services/cnab_parser_service.rb"
    click S2 "https://github.com/alexsantosfilho/desafio-dev/blob/main/app/services/cnab_importer.rb"
    click S3 "https://github.com/alexsantosfilho/desafio-dev/blob/main/app/services/transactions/import_service.rb"
    click S4 "https://github.com/alexsantosfilho/desafio-dev/blob/main/app/services/store_balance_updater.rb"

    %% Click Events - Jobs
    click Jobs "https://github.com/alexsantosfilho/desafio-dev/blob/main/app/jobs/transactions/import_job.rb"

    %% Click Events - External Services
    click Auth "https://github.com/alexsantosfilho/desafio-dev/blob/main/config/initializers/omniauth.rb"
    click Channels "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/channels/application_cable"
    click JSChannels "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/javascript/channels"

    %% Click Events - Database
    click Models "https://github.com/alexsantosfilho/desafio-dev/tree/main/app/models"
    click DBConfig "https://github.com/alexsantosfilho/desafio-dev/blob/main/config/database.yml"

    %% Click Events - Deployment & Dev Tools
    click Dockerfile "https://github.com/alexsantosfilho/desafio-dev/tree/main/Dockerfile"
    click DockerCompose "https://github.com/alexsantosfilho/desafio-dev/blob/main/docker-compose.yml"
    click GitHooks "https://github.com/alexsantosfilho/desafio-dev/blob/main/.git-hooks"
    click Overcommit "https://github.com/alexsantosfilho/desafio-dev/blob/main/.overcommit.yml"
```
