# therealstone-dev/oilskinofficialrepo architecture

> Architecture diagram of the GitHub repository therealstone-dev/oilskinofficialrepo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/therealstone-dev/oilskinofficialrepo
- Repository: https://github.com/therealstone-dev/oilskinofficialrepo

## Overview

#### Purpose and Runtime

Oil Skin is a server-rendered Python e-commerce application for skincare products. It runs from `app.py`, requires a Python virtual environment and packages in `requirements.txt`, and connects to MySQL through `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, and `MYSQL_DB`.

#### Application Composition

The application is organized as route/controller modules, model-based database access, Jinja templates, and a billing service:
- Startup and likely Flask application/blueprint registration: `app.py`, `src/routes/__init__.py`
- Database connection boundary: `src/database/db_mysql.py`
- Domain persistence layer: `src/models/ModeloProductos.py`, `src/models/ModeloPedido.py`, `src/models/ModeloUsuario.py`

#### Public Storefront Flow

Public-facing routes serve the catalog, category listings, product detail, cart, checkout, and informational pages. Requests pass from route modules to product/category/cart/order models and render Jinja pages:
- Route boundary: `src/routes/main_routes.py`, `src/routes/user_routes.py`
- Storefront views: `src/templates/index.jinja`, `src/templates/category.jinja`, `src/templates/detalle.jinja`
- Purchase views: `src/templates/carrito.jinja`, `src/templates/checkout.jinja`

#### Authentication and Customer Accounts

Authentication is separated into dedicated routes, form definitions, and authorization utilities. Registered users access profile-oriented cart, checkout, and order-history views.
- Auth entry points: `src/routes/auth_routes.py`, `src/forms/auth_forms.py`
- Access-control helpers: `src/utils/auth_utils.py`
- User and cart persistence: `src/models/ModeloUsuario.py`, `src/models/ModeloCarrito.py`
- Account UI: `src/templates/profile/profile.html`, `src/templates/profile/profile-pedidos.html`

#### Order, Checkout, and Invoicing Boundary

Checkout converts cart and customer state into orders managed by the order model. Invoicing is isolated as a service, producing invoice-oriented rendering paths rather than being embedded directly in route/template code.
- Order/cart domain: `src/models/ModeloPedido.py`, `src/models/ModeloCarrito.py`
- Invoice service: `src/services/facturacion_service.py`
- Invoice output: `src/templates/factura.html`, `src/templates/ver_factura.html`

#### Administration and Reporting

Administrative routes operate separately from the public storefront and expose inventory, sales, user, and metric dashboards. The admin model and dedicated SQL views indicate reporting is substantially database-driven.
- Admin boundary: `src/routes/admin_routes.py`, `src/models/ModeloAdmin.py`
- Dashboard views: `src/templates/admin/dashboard_inventario.html`, `src/templates/admin/dashboard_ventas.html`
- Reporting SQL: `database/vistas_admin.sql`, `database/vistas.sql`

#### Database and Presentation Infrastructure

MySQL is the primary persistence and reporting platform. Database schema, queries, and views are versioned as SQL artifacts. Jinja uses shared Bootstrap and Tailwind layout/component families; static assets support both.
- Database artifacts: `database/defiv.sql`, `database/queries.sql`, `database/vistas.sql`
- Shared presentation shells: `src/templates/components/boostrap/layout_boostrap.jinja`, `src/templates/components/tailwind/layout.jinja`
- Styling infrastructure: `package.json`, `tailwind.config.js`, `src/static/css/style.css`

Main entry points: [`src/database/db_mysql.py`](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/database/db_mysql.py) (MySQL connection), [`src/routes/__init__.py`](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/__init__.py) (Route registry), [`src/routes/user_routes.py`](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/user_routes.py) (Customer routes), [`src/routes/auth_routes.py`](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/auth_routes.py) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application Runtime"]
  node_app{{"Flask startup<br/>application entry<br/>[app.py]"}}
  node_route_registry["Route registry<br/>blueprint registry<br/>[__init__.py]"]
end

subgraph group_storefront["Storefront &amp; Accounts"]
  node_public_routes["Storefront routes<br/>controllers<br/>[main_routes.py]"]
  node_user_routes["Customer routes<br/>controllers<br/>[user_routes.py]"]
  node_auth_routes["Auth routes<br/>controllers<br/>[auth_routes.py]"]
  node_auth_forms["Auth forms<br/>form definitions<br/>[auth_forms.py]"]
  node_auth_utils["Access control<br/>authorization utilities<br/>[auth_utils.py]"]
  node_storefront_views["Catalog views<br/>Jinja templates<br/>[index.jinja]"]
  node_purchase_views["Cart &amp; checkout views<br/>Jinja templates<br/>[carrito.jinja]"]
  node_account_views["Account views<br/>Jinja templates<br/>[profile.html]"]
end

subgraph group_domain["Domain &amp; Billing"]
  node_product_model["Product catalog<br/>persistence model<br/>[ModeloProductos.py]"]
  node_user_model["Customer accounts<br/>persistence model<br/>[ModeloUsuario.py]"]
  node_cart_model["Shopping carts<br/>persistence model<br/>[ModeloCarrito.py]"]
  node_order_model["Orders<br/>persistence model<br/>[ModeloPedido.py]"]
  node_invoicing["Invoicing service<br/>billing service"]
  node_invoice_views["Invoice views<br/>Jinja templates<br/>[factura.html]"]
end

subgraph group_admin["Administration"]
  node_admin_routes["Admin routes<br/>controllers<br/>[admin_routes.py]"]
  node_admin_model["Admin reporting<br/>reporting model<br/>[ModeloAdmin.py]"]
  node_admin_views["Admin dashboards<br/>Jinja templates"]
end

subgraph group_data["Data &amp; Presentation"]
  node_mysql_boundary[("MySQL connection<br/>database adapter<br/>[db_mysql.py]")]
  node_sql_artifacts["Schema &amp; reporting SQL<br/>SQL artifacts<br/>[defiv.sql]"]
  node_shared_layouts["Shared layouts<br/>Jinja layout families"]
end

node_app -->|"loads"| node_route_registry
node_route_registry -->|"registers"| node_public_routes
node_route_registry -->|"registers"| node_user_routes
node_route_registry -->|"registers"| node_auth_routes
node_route_registry -->|"registers"| node_admin_routes
node_public_routes -->|"reads catalog"| node_product_model
node_public_routes -->|"renders"| node_storefront_views
node_user_routes -->|"manages"| node_cart_model
node_user_routes -->|"creates orders"| node_order_model
node_user_routes -->|"renders"| node_purchase_views
node_auth_routes -->|"validates"| node_auth_forms
node_auth_routes -->|"uses"| node_auth_utils
node_auth_routes -->|"authenticates"| node_user_model
node_user_routes -->|"renders"| node_account_views
node_order_model -->|"supplies order data"| node_invoicing
node_invoicing -->|"renders"| node_invoice_views
node_admin_routes -->|"queries"| node_admin_model
node_admin_routes -->|"renders"| node_admin_views
node_product_model -->|"persists to"| node_mysql_boundary
node_user_model -->|"persists to"| node_mysql_boundary
node_cart_model -->|"persists to"| node_mysql_boundary
node_order_model -->|"persists to"| node_mysql_boundary
node_admin_model -->|"reads reports"| node_mysql_boundary
node_sql_artifacts -.->|"defines schema and views"| node_mysql_boundary
node_storefront_views -.->|"extends"| node_shared_layouts
node_purchase_views -.->|"extends"| node_shared_layouts
node_admin_views -.->|"extends"| node_shared_layouts

click node_app "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/app.py"
click node_route_registry "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/__init__.py"
click node_public_routes "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/main_routes.py"
click node_user_routes "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/user_routes.py"
click node_auth_routes "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/auth_routes.py"
click node_auth_forms "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/forms/auth_forms.py"
click node_auth_utils "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/utils/auth_utils.py"
click node_storefront_views "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/index.jinja"
click node_purchase_views "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/carrito.jinja"
click node_account_views "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/profile/profile.html"
click node_product_model "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloProductos.py"
click node_user_model "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloUsuario.py"
click node_cart_model "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloCarrito.py"
click node_order_model "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloPedido.py"
click node_invoicing "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/services/facturacion_service.py"
click node_invoice_views "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/factura.html"
click node_admin_routes "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/admin_routes.py"
click node_admin_model "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloAdmin.py"
click node_admin_views "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/admin/dashboard_inventario.html"
click node_mysql_boundary "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/database/db_mysql.py"
click node_sql_artifacts "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/database/defiv.sql"
click node_shared_layouts "https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/components/boostrap/layout_boostrap.jinja"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_route_registry toneBlue
class node_public_routes,node_user_routes,node_auth_routes,node_auth_forms,node_auth_utils,node_storefront_views,node_purchase_views,node_account_views toneAmber
class node_product_model,node_user_model,node_cart_model,node_order_model,node_invoicing,node_invoice_views toneMint
class node_admin_routes,node_admin_model,node_admin_views toneRose
class node_mysql_boundary,node_sql_artifacts,node_shared_layouts toneIndigo
```

## Components

### Application Runtime

- [Flask startup](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/app.py): application entry · Creates the application and registers routes. · `app.py`
- [Route registry](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/__init__.py): blueprint registry · `src/routes/__init__.py`

### Storefront & Accounts

- [Storefront routes](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/main_routes.py): controllers · `src/routes/main_routes.py`
- [Customer routes](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/user_routes.py): controllers · Handles customer-facing cart and checkout pages. · `src/routes/user_routes.py`
- [Auth routes](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/auth_routes.py): controllers · `src/routes/auth_routes.py`
- [Auth forms](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/forms/auth_forms.py): form definitions · `src/forms/auth_forms.py`
- [Access control](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/utils/auth_utils.py): authorization utilities · `src/utils/auth_utils.py`
- [Catalog views](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/index.jinja): Jinja templates · Catalog, category, and product-detail pages. · `src/templates/index.jinja`
- [Cart & checkout views](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/carrito.jinja): Jinja templates · `src/templates/carrito.jinja`
- [Account views](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/profile/profile.html): Jinja templates · Profile and order-history pages. · `src/templates/profile/profile.html`

### Domain & Billing

- [Product catalog](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloProductos.py): persistence model · `src/models/ModeloProductos.py`
- [Customer accounts](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloUsuario.py): persistence model · `src/models/ModeloUsuario.py`
- [Shopping carts](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloCarrito.py): persistence model · `src/models/ModeloCarrito.py`
- [Orders](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloPedido.py): persistence model · `src/models/ModeloPedido.py`
- [Invoicing service](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/services/facturacion_service.py): billing service · Produces invoice-oriented output from orders. · `src/services/facturacion_service.py`
- [Invoice views](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/factura.html): Jinja templates · `src/templates/factura.html`

### Administration

- [Admin routes](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/routes/admin_routes.py): controllers · `src/routes/admin_routes.py`
- [Admin reporting](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/models/ModeloAdmin.py): reporting model · `src/models/ModeloAdmin.py`
- [Admin dashboards](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/admin/dashboard_inventario.html): Jinja templates · Inventory and sales dashboards. · `src/templates/admin/dashboard_inventario.html`

### Data & Presentation

- [MySQL connection](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/database/db_mysql.py): database adapter · Connects using MYSQL environment settings. · `src/database/db_mysql.py`
- [Schema & reporting SQL](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/database/defiv.sql): SQL artifacts · Versioned schema, queries, and reporting views. · `database/defiv.sql`
- [Shared layouts](https://github.com/therealstone-dev/oilskinofficialrepo/blob/main/src/templates/components/boostrap/layout_boostrap.jinja): Jinja layout families · Bootstrap and Tailwind presentation shells. · `src/templates/components/boostrap/layout_boostrap.jinja`

## Connections

- Flask startup → Route registry: loads
- Route registry → Storefront routes: registers
- Route registry → Customer routes: registers
- Route registry → Auth routes: registers
- Route registry → Admin routes: registers
- Storefront routes → Product catalog: reads catalog
- Storefront routes → Catalog views: renders
- Customer routes → Shopping carts: manages
- Customer routes → Orders: creates orders
- Customer routes → Cart & checkout views: renders
- Auth routes → Auth forms: validates
- Auth routes → Access control: uses
- Auth routes → Customer accounts: authenticates
- Customer routes → Account views: renders
- Orders → Invoicing service: supplies order data
- Invoicing service → Invoice views: renders
- Admin routes → Admin reporting: queries
- Admin routes → Admin dashboards: renders
- Product catalog → MySQL connection: persists to
- Customer accounts → MySQL connection: persists to
- Shopping carts → MySQL connection: persists to
- Orders → MySQL connection: persists to
- Admin reporting → MySQL connection: reads reports
- Schema & reporting SQL → MySQL connection: defines schema and views
- Catalog views → Shared layouts: extends
- Cart & checkout views → Shared layouts: extends
- Admin dashboards → Shared layouts: extends