How leosfreitas/regula-back works
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│
└────────────┘