# leosfreitas/regula-back architecture

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

- Interactive diagram: https://gitdiagram.com/leosfreitas/regula-back
- Repository: https://github.com/leosfreitas/regula-back

## Overview

##### Project Type & Purpose
- This is a Python-based REST API backend (no UI) deployed (Procfile, runtime.txt) likely on Heroku or similar PaaS.
- It exposes endpoints for three main user domains: Admin, Public (unauthenticated), and User.
- It implements business logic (“use_cases”), domain entities, token-based auth, ML-driven claim analysis, and email notifications.

##### Top-Level Architectural Layers (from top to bottom)
a. Client / API Interface (top)
b. HTTP Routing & Middlewares
c. Application Core (Use Cases & Entities)
d. Persistence & External Services
e. Infrastructure & Deployment (bottom)

##### Components & Their Relationships
a. Client / API Interface
- External callers (Web/Mobile clients or API Gateway)
b. HTTP Routing & Middlewares
- src/app.py defines Flask/FastAPI routes for Admin, Public, User
- Two middleware components:
- validate_admin_auth_token
- validate_user_auth_token
c. Application Core (center)
- Package “use_cases” subdivided into three vertical columns:
- Admin Use Cases (auth, contact, sinistro, users, headbar, my_account)
- Public Use Cases (password reset, send recovery email, contact creation)
- User Use Cases (auth, headbar, my_account, sinistro CRUD)
- At the center of this layer, place Entities (admin, contact, sinistro, user) and DTOs mapped into each Use Case
d. Persistence & External Services
- Repositories (admin_repository, contact_repository, sinistro_repository, user_repository) connect Use Cases → Database
- Utils:
- send_email → External Email SMTP/Service
- encode_hmac_hash, get_session_info (internal utilities)
e. Infrastructure & Deployment
- Config module (src/config/config.py) reads environment (runtime.txt, requirements.txt)
- Logging & Monitoring (optional)

##### Architectural Patterns & Principles
- Hexagonal (Ports & Adapters):
– Adapters: HTTP routes, Middlewares, Repositories, Utils, ML pipeline
– Core: Use Cases + Entities
- Separation of Concerns:
– Authentication, Business Logic, Data Access, Configuration
- Dependency Injection via config module

##### Technology Call-outs
- Python 3.x (runtime.txt) with Flask or FastAPI (app.py)
- ORM or direct DB client in repositories
- ML library (scikit-learn / XGBoost) for claim analysis
- Email SMTP client in utils/send_email.py
- HMAC token utils for auth

##### Putting It All Together
┌────────────┐
│Clients/API │
├────────────┤
│Routing &   │
│Middlewares │
├────────────┤
│Use Cases   │
│ & Entities │
├────────────┤
│Repositories│
│ & Ext Svcs │
├────────────┤
│Infrastructure│
└────────────┘

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client / API Interface
    subgraph "Client / API Interface"
        direction TB
        ExternalClients["External Callers"]:::external
    end
    click ExternalClients "https://github.com/leosfreitas/regula-back/blob/main/src/app.py"

    %% HTTP Routing & Middlewares
    subgraph "HTTP Routing & Middlewares"
        direction TB
        Routing["Routes (src/app.py)"]:::blue
        AdminMW["validate_admin_auth_token"]:::blue
        UserMW["validate_user_auth_token"]:::blue
    end
    click Routing "https://github.com/leosfreitas/regula-back/blob/main/src/app.py"
    click AdminMW "https://github.com/leosfreitas/regula-back/blob/main/src/middlewares/validate_admin_auth_token.py"
    click UserMW "https://github.com/leosfreitas/regula-back/blob/main/src/middlewares/validate_user_auth_token.py"

    ExternalClients -->|HTTP| Routing
    Routing -->|calls| AdminMW
    Routing -->|calls| UserMW

    %% Application Core
    subgraph "Application Core (Use Cases & Entities)"
        direction TB
        subgraph "Admin Use Cases"
            AdminUC["Admin Use Cases"]:::green
        end
        subgraph "Public Use Cases"
            PublicUC["Public Use Cases"]:::green
        end
        subgraph "User Use Cases"
            UserUC["User Use Cases"]:::green
        end
        subgraph Entities
            direction TB
            AdminEntity["admin"]:::green
            ContactEntity["contact"]:::green
            SinistroEntity["sinistro"]:::green
            UserEntity["user"]:::green
        end
    end
    click AdminUC "https://github.com/leosfreitas/regula-back/tree/main/src/use_cases/admin/"
    click PublicUC "https://github.com/leosfreitas/regula-back/tree/main/src/use_cases/public/"
    click UserUC "https://github.com/leosfreitas/regula-back/tree/main/src/use_cases/user/"
    click AdminEntity "https://github.com/leosfreitas/regula-back/blob/main/src/entities/admin.py"
    click ContactEntity "https://github.com/leosfreitas/regula-back/blob/main/src/entities/contact.py"
    click SinistroEntity "https://github.com/leosfreitas/regula-back/blob/main/src/entities/sinistro.py"
    click UserEntity "https://github.com/leosfreitas/regula-back/blob/main/src/entities/user.py"

    AdminMW -->|"invoke"| AdminUC
    UserMW -->|"invoke"| UserUC
    PublicUC -->|"direct"| Entities
    AdminUC -->|"uses"| Entities
    UserUC -->|"uses"| Entities
    Entities -->|"provides data"| AdminUC
    Entities -->|"provides data"| UserUC
    Entities -->|"provides data"| PublicUC

    %% Persistence & External Services
    subgraph "Persistence & External Services"
        direction TB
        AdminRepo["admin_repository"]:::orange
        ContactRepo["contact_repository"]:::orange
        SinistroRepo["sinistro_repository"]:::orange
        UserRepo["user_repository"]:::orange
        DB["Database"]:::external
        EmailUtil["send_email"]:::orange
        HMACUtil["encode_hmac_hash"]:::orange
        SessionUtil["get_session_info"]:::orange
        MLPipeline["Local ML Pipeline"]:::orange
        Artifacts["ML Artifacts"]:::orange
    end
    click AdminRepo "https://github.com/leosfreitas/regula-back/blob/main/src/repositories/admin_repository.py"
    click ContactRepo "https://github.com/leosfreitas/regula-back/blob/main/src/repositories/contact_repository.py"
    click SinistroRepo "https://github.com/leosfreitas/regula-back/blob/main/src/repositories/sinistro_repository.py"
    click UserRepo "https://github.com/leosfreitas/regula-back/blob/main/src/repositories/user_repository.py"
    click EmailUtil "https://github.com/leosfreitas/regula-back/blob/main/src/utils/send_email.py"
    click HMACUtil "https://github.com/leosfreitas/regula-back/blob/main/src/utils/encode_hmac_hash.py"
    click SessionUtil "https://github.com/leosfreitas/regula-back/blob/main/src/utils/get_session_info.py"
    click Artifacts "https://github.com/leosfreitas/regula-back/tree/main/src/use_cases/admin/sinistro/analyze_sinistro/artifacts/"

    AdminUC -->|SQL| AdminRepo
    PublicUC -->|SQL| ContactRepo
    UserUC -->|SQL| UserRepo
    AdminUC -->|SQL| SinistroRepo
    UserUC -->|SQL| SinistroRepo
    AdminRepo -->|reads/writes| DB
    ContactRepo -->|reads/writes| DB
    UserRepo -->|reads/writes| DB
    SinistroRepo -->|reads/writes| DB
    PublicUC -->|SMTP| EmailUtil
    EmailUtil -->|SMTP| ExternalEmail[("Email Service")]:::external
    AdminUC -->|analyze| MLPipeline
    MLPipeline -->|loads| Artifacts

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        direction TB
        Config["config module"]:::gray
        Procfile["Procfile"]:::gray
        Runtime["runtime.txt"]:::gray
        Req["requirements.txt"]:::gray
        Deployment["Heroku/Docker/K8s"]:::gray
    end
    click Config "https://github.com/leosfreitas/regula-back/blob/main/src/config/config.py"
    click Procfile "https://github.com/leosfreitas/regula-back/tree/main/Procfile"
    click Runtime "https://github.com/leosfreitas/regula-back/blob/main/runtime.txt"
    click Req "https://github.com/leosfreitas/regula-back/blob/main/requirements.txt"

    DB -->|env| Config
    EmailUtil -->|env| Config
    MLPipeline -->|env| Config
    Config -->|deploy| Deployment

    %% Styles
    classDef blue fill:#cce5ff,stroke:#004085,color:#004085;
    classDef green fill:#d4edda,stroke:#155724,color:#155724;
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404;
    classDef gray fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
```
