# nafery/apiferramas architecture

> Architecture diagram of the GitHub repository nafery/apiferramas, 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/nafery/apiferramas
- Repository: https://github.com/nafery/apiferramas

## Overview

##### Project type and purpose
- This is a RESTful, full-stack backend API (no UI) for Ferramas hardware store. It exposes endpoints for product & user management, currency conversion, and Transbank payment integration.
- It follows a layered (n-tier) architecture: Routes → Services → Models → Database, with utility modules for shared configuration.

##### Main components
a. Flask Application (app.py) – the entry point that wires up routes, DB connection, and starts the server.
b. Routes Layer (api/routes) – HTTP controllers that define endpoints (/products, /users, /currency, /webpay).
c. Services Layer (api/services) – business logic orchestrating data flow and external integrations:
- product_service.py, user_service.py, category_services.py
- currency_service.py (calls external exchange-rate APIs via requests)
- webpay_service.py (calls Transbank SDK)
d. Models Layer (api/models) – data-access objects encapsulating SQL queries for products, users, categories.
e. Database Layer (api/db/database.py) – configuration and connection to MySQL.
f. Utils (api/utils/transbank_config.py) – shared config for payment SDK.
g. External Services – third-party currency-rate API and Transbank payment gateway.
h. MySQL Database (ferramas.sql schema).

##### Relationships and data flow
1. Client (Postman/browser) → HTTP Request
2. Flask app → Routes Layer
3. Routes calls Services
4. Services ↔ Models (SQL queries) → MySQL
5. Services → External APIs (currency, webpay)
6. Services returns processed data → Routes
7. Routes → HTTP Response to Client

##### Architectural patterns and principles
- Layered architecture (separation of concerns): controllers, business logic, data access, config.
- Single responsibility per module and clear dependency direction (Routes → Services → Models).
- Reusable utilities for config (e.g., Transbank credentials).
- External communication abstracted in service modules.

##### Essential elements
- Components: Flask App, Routes, Services, Models, Database, Utils, External APIs
- Clear labels: directory names, key classes/files
- Boundaries: show that models never call services or routes directly

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client (Postman)"]:::client -->|"HTTP Request"| App["Flask Application<br>app.py"]:::app
    App -->|"Initialize Routes & DB"| Routes["Routes Layer"]:::routes

    subgraph "api/routes"
        PRoute["/products"]:::routes
        URoute["/users"]:::routes
        CRoute["/currency"]:::routes
        WRoute["/webpay"]:::routes
    end
    Routes -->|calls| PRoute
    Routes -->|calls| URoute
    Routes -->|calls| CRoute
    Routes -->|calls| WRoute

    subgraph "api/services"
        ProdSvc["Product Service<br>product_service.py"]:::services
        UserSvc["User Service<br>user_service.py"]:::services
        CatSvc["Category Service<br>category_services.py"]:::services
        CurrSvc["Currency Service<br>currency_service.py"]:::services
        WebpaySvc["Webpay Service<br>webpay_service.py"]:::services
    end
    PRoute -->|uses| ProdSvc
    URoute -->|uses| UserSvc
    PRoute -->|uses| CatSvc
    CRoute -->|uses| CurrSvc
    WRoute -->|uses| WebpaySvc

    ProdSvc -->|SQL Queries| ProdMod
    UserSvc -->|SQL Queries| UserMod
    CatSvc -->|SQL Queries| CatMod
    CurrSvc -->|HTTP API Calls| CurrencyAPI
    WebpaySvc -->|SDK/API Calls| Transbank
    WebpaySvc -->|loads config| TransbankCfg

    subgraph "api/models & db"
        ProdMod["Product Model<br>product.py"]:::models
        UserMod["User Model<br>user.py"]:::models
        CatMod["Category Model<br>category.py"]:::models
        DBConfig["Database Config<br>database.py"]:::models
    end
    DBConfig -->|provides connection| ProdMod
    DBConfig -->|provides connection| UserMod
    DBConfig -->|provides connection| CatMod

    ProdMod -->|SQL| MySQL[(MySQL Database)]:::db
    UserMod -->|SQL| MySQL
    CatMod -->|SQL| MySQL
    DBConfig -->|connects to| MySQL

    CurrencyAPI["Currency Rate API"]:::external
    Transbank["Transbank Gateway"]:::external
    TransbankCfg["Transbank Config Util<br>transbank_config.py"]:::utils

    click App "https://github.com/nafery/apiferramas/blob/main/app.py"
    click Routes "https://github.com/nafery/apiferramas/blob/main/api/routes/route.py"
    click PRoute "https://github.com/nafery/apiferramas/blob/main/api/routes/route.py"
    click ProdSvc "https://github.com/nafery/apiferramas/blob/main/api/services/product_service.py"
    click UserSvc "https://github.com/nafery/apiferramas/blob/main/api/services/user_service.py"
    click CatSvc "https://github.com/nafery/apiferramas/blob/main/api/services/category_services.py"
    click CurrSvc "https://github.com/nafery/apiferramas/blob/main/api/services/currency_service.py"
    click WebpaySvc "https://github.com/nafery/apiferramas/blob/main/api/services/webpay_service.py"
    click ProdMod "https://github.com/nafery/apiferramas/blob/main/api/models/product.py"
    click UserMod "https://github.com/nafery/apiferramas/blob/main/api/models/user.py"
    click CatMod "https://github.com/nafery/apiferramas/blob/main/api/models/category.py"
    click DBConfig "https://github.com/nafery/apiferramas/blob/main/api/db/database.py"
    click TransbankCfg "https://github.com/nafery/apiferramas/blob/main/api/utils/transbank_config.py"

    classDef client fill:#D0E6FF,stroke:#2F80ED,color:#2F80ED;
    classDef app fill:#E8F0FE,stroke:#1C4587,color:#1C4587,stroke-width:2px;
    classDef routes fill:#D6EEFF,stroke:#1565C0,color:#1565C0;
    classDef services fill:#E6F4EA,stroke:#2E7D32,color:#2E7D32;
    classDef models fill:#FFF4E5,stroke:#E65100,color:#E65100;
    classDef db fill:#FFF4E5,stroke:#E65100,color:#E65100,stroke-dasharray: 5 5;
    classDef external fill:#F2F2F2,stroke:#666666,color:#666666;
    classDef utils fill:#FFFDE7,stroke:#F9A825,color:#F9A825;
```
