# sgsanchez/progav-tg1-grupo9 architecture

> Architecture diagram of the GitHub repository sgsanchez/progav-tg1-grupo9, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sgsanchez/progav-tg1-grupo9
- Repository: https://github.com/sgsanchez/progav-tg1-grupo9

## Overview

Sistema de ventas y facturación expuesto como API REST. El recorrido principal va desde el cliente HTTP, por los controladores y servicios, hasta el registro de ventas con validación de cliente y stock, actualización de inventario y persistencia; las respuestas exponen ventas y comprobantes. También se documentan administración de clientes y productos, consultas de inventario y ranking, auditoría paginada y generación de comprobantes bloqueante o asíncrona. Los vínculos entre módulos se limitan a referencias del índice de fuentes y relaciones descritas explícitamente en el README; el detalle de fuentes no muestreadas no se presume.

Main entry points: [`src/main/java/ec/edu/espe/ventas/service/VentaService.java`](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/VentaService.java) (Ventas y stock), [`src/main/java/ec/edu/espe/ventas/entity`](https://github.com/sgsanchez/progav-tg1-grupo9/tree/main/src/main/java/ec/edu/espe/ventas/entity) (Modelo comercial), [`src/main/java/ec/edu/espe/ventas/controller/ProductoController.java`](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/ProductoController.java) (API productos), [`src/main/java/ec/edu/espe/ventas/controller/VentaController.java`](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/VentaController.java) (API ventas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API y contratos"]
  node_customer_api["API clientes"]
  node_product_api["API productos"]
  node_sales_api["API ventas"]
  node_audit_api["API auditoría"]
  node_contracts["DTO y mappers"]
end

subgraph group_domain["Operación comercial"]
  node_customer_service["Gestión clientes"]
  node_product_service["Productos e inventario"]
  node_sales_service["Ventas y stock<br/>[VentaService.java]"]
  node_receipt_service["Comprobantes"]
end

subgraph group_data["Persistencia"]
  node_entities["Modelo comercial"]
  node_customer_repo[("Repositorio clientes")]
  node_product_repo[("Repositorio productos")]
  node_sales_repo[("Repositorios venta y detalle")]
end

subgraph group_cross["Servicios transversales"]
  node_audit_service["Consulta auditoría"]
  node_audit_aspect["Auditoría AOP"]
  node_audit_repo[("Repositorio auditoría")]
  node_http_guard["Interceptor API key"]
  node_errors["Errores HTTP"]
end

node_user(("Cliente HTTP"))

node_user -->|"solicita"| node_customer_api
node_user -->|"solicita"| node_product_api
node_user -->|"solicita"| node_sales_api
node_user -->|"consulta"| node_audit_api
node_http_guard -->|"protege /api/**"| node_customer_api
node_customer_api -->|"invoca"| node_customer_service
node_product_api -->|"invoca"| node_product_service
node_product_api -->|"consulta ranking"| node_sales_service
node_sales_api -->|"invoca"| node_sales_service
node_sales_api -->|"solicita comprobante"| node_receipt_service
node_audit_api -->|"invoca"| node_audit_service
node_customer_service -->|"lee y guarda"| node_customer_repo
node_product_service -->|"lee y guarda"| node_product_repo
node_sales_service -->|"consulta y actualiza stock"| node_product_repo
node_sales_service -->|"busca cliente"| node_customer_repo
node_sales_service -.->|"persiste ventas"| node_sales_repo
node_customer_repo -->|"persiste entidades"| node_entities
node_product_repo -->|"persiste entidades"| node_entities
node_sales_repo -->|"persiste entidades"| node_entities
node_customer_service -->|"convierte datos"| node_contracts
node_product_service -->|"convierte datos"| node_contracts
node_sales_service -->|"produce respuestas"| node_contracts
node_audit_service -->|"consulta registros"| node_audit_repo
node_audit_aspect -->|"guarda auditoría"| node_audit_repo
node_audit_repo -->|"persiste auditoría"| node_entities
node_audit_aspect -->|"intercepta @Auditable"| node_sales_service
node_errors -->|"devuelve error uniforme"| node_user

click node_customer_api "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/ClienteController.java"
click node_product_api "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/ProductoController.java"
click node_sales_api "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/VentaController.java"
click node_audit_api "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/AuditoriaController.java"
click node_contracts "https://github.com/sgsanchez/progav-tg1-grupo9/tree/main/src/main/java/ec/edu/espe/ventas/dto"
click node_customer_service "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/ClienteService.java"
click node_product_service "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/ProductoService.java"
click node_sales_service "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/VentaService.java"
click node_receipt_service "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/ComprobanteService.java"
click node_entities "https://github.com/sgsanchez/progav-tg1-grupo9/tree/main/src/main/java/ec/edu/espe/ventas/entity"
click node_customer_repo "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/repository/ClienteRepository.java"
click node_product_repo "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/repository/ProductoRepository.java"
click node_sales_repo "https://github.com/sgsanchez/progav-tg1-grupo9/tree/main/src/main/java/ec/edu/espe/ventas/repository"
click node_audit_service "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/AuditoriaService.java"
click node_audit_aspect "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/aspect/AuditoriaAspect.java"
click node_audit_repo "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/repository/AuditoriaRepository.java"
click node_http_guard "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/interceptor/ApiKeyInterceptor.java"
click node_errors "https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/exception/GlobalExceptionHandler.java"

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_customer_api,node_product_api,node_sales_api,node_audit_api,node_contracts,node_user toneBlue
class node_customer_service,node_product_service,node_sales_service,node_receipt_service toneAmber
class node_entities,node_customer_repo,node_product_repo,node_sales_repo toneMint
class node_audit_service,node_audit_aspect,node_audit_repo,node_http_guard,node_errors toneRose
```

## Components

### API y contratos

- [API clientes](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/ClienteController.java): `src/main/java/ec/edu/espe/ventas/controller/ClienteController.java`
- [API productos](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/ProductoController.java): `src/main/java/ec/edu/espe/ventas/controller/ProductoController.java`
- [API ventas](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/VentaController.java): `src/main/java/ec/edu/espe/ventas/controller/VentaController.java`
- [API auditoría](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/controller/AuditoriaController.java): `src/main/java/ec/edu/espe/ventas/controller/AuditoriaController.java`
- [DTO y mappers](https://github.com/sgsanchez/progav-tg1-grupo9/tree/main/src/main/java/ec/edu/espe/ventas/dto): `src/main/java/ec/edu/espe/ventas/dto`

### Operación comercial

- [Gestión clientes](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/ClienteService.java): `src/main/java/ec/edu/espe/ventas/service/ClienteService.java`
- [Productos e inventario](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/ProductoService.java): `src/main/java/ec/edu/espe/ventas/service/ProductoService.java`
- [Ventas y stock](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/VentaService.java): `src/main/java/ec/edu/espe/ventas/service/VentaService.java`
- [Comprobantes](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/ComprobanteService.java): `src/main/java/ec/edu/espe/ventas/service/ComprobanteService.java`

### Persistencia

- [Modelo comercial](https://github.com/sgsanchez/progav-tg1-grupo9/tree/main/src/main/java/ec/edu/espe/ventas/entity): `src/main/java/ec/edu/espe/ventas/entity`
- [Repositorio clientes](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/repository/ClienteRepository.java): `src/main/java/ec/edu/espe/ventas/repository/ClienteRepository.java`
- [Repositorio productos](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/repository/ProductoRepository.java): `src/main/java/ec/edu/espe/ventas/repository/ProductoRepository.java`
- [Repositorios venta y detalle](https://github.com/sgsanchez/progav-tg1-grupo9/tree/main/src/main/java/ec/edu/espe/ventas/repository): `src/main/java/ec/edu/espe/ventas/repository`

### Servicios transversales

- [Consulta auditoría](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/service/AuditoriaService.java): `src/main/java/ec/edu/espe/ventas/service/AuditoriaService.java`
- [Auditoría AOP](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/aspect/AuditoriaAspect.java): `src/main/java/ec/edu/espe/ventas/aspect/AuditoriaAspect.java`
- [Repositorio auditoría](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/repository/AuditoriaRepository.java): `src/main/java/ec/edu/espe/ventas/repository/AuditoriaRepository.java`
- [Interceptor API key](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/interceptor/ApiKeyInterceptor.java): `src/main/java/ec/edu/espe/ventas/interceptor/ApiKeyInterceptor.java`
- [Errores HTTP](https://github.com/sgsanchez/progav-tg1-grupo9/blob/main/src/main/java/ec/edu/espe/ventas/exception/GlobalExceptionHandler.java): `src/main/java/ec/edu/espe/ventas/exception/GlobalExceptionHandler.java`

### Other components

- **Cliente HTTP**

## Connections

- Cliente HTTP → API clientes: solicita
- Cliente HTTP → API productos: solicita
- Cliente HTTP → API ventas: solicita
- Cliente HTTP → API auditoría: consulta
- Interceptor API key → API clientes: protege /api/**
- API clientes → Gestión clientes: invoca (evidence: `src/main/java/ec/edu/espe/ventas/controller/ClienteController.java`)
- API productos → Productos e inventario: invoca (evidence: `src/main/java/ec/edu/espe/ventas/controller/ProductoController.java`)
- API productos → Ventas y stock: consulta ranking (evidence: `src/main/java/ec/edu/espe/ventas/controller/ProductoController.java`)
- API ventas → Ventas y stock: invoca (evidence: `src/main/java/ec/edu/espe/ventas/controller/VentaController.java`)
- API ventas → Comprobantes: solicita comprobante (evidence: `src/main/java/ec/edu/espe/ventas/controller/VentaController.java`)
- API auditoría → Consulta auditoría: invoca (evidence: `src/main/java/ec/edu/espe/ventas/controller/AuditoriaController.java`)
- Gestión clientes → Repositorio clientes: lee y guarda (evidence: `src/main/java/ec/edu/espe/ventas/service/ClienteService.java`)
- Productos e inventario → Repositorio productos: lee y guarda (evidence: `src/main/java/ec/edu/espe/ventas/service/ProductoService.java`)
- Ventas y stock → Repositorio productos: consulta y actualiza stock (evidence: `src/main/java/ec/edu/espe/ventas/service/VentaService.java`)
- Ventas y stock → Repositorio clientes: busca cliente (evidence: `src/main/java/ec/edu/espe/ventas/service/VentaService.java`)
- Ventas y stock → Repositorios venta y detalle: persiste ventas (evidence: `src/main/java/ec/edu/espe/ventas/service/VentaService.java`)
- Repositorio clientes → Modelo comercial: persiste entidades (evidence: `src/main/java/ec/edu/espe/ventas/repository/ClienteRepository.java`)
- Repositorio productos → Modelo comercial: persiste entidades (evidence: `src/main/java/ec/edu/espe/ventas/repository/ProductoRepository.java`)
- Repositorios venta y detalle → Modelo comercial: persiste entidades (evidence: `src/main/java/ec/edu/espe/ventas/repository/ProductoRepository.java`)
- Gestión clientes → DTO y mappers: convierte datos (evidence: `src/main/java/ec/edu/espe/ventas/service/ClienteService.java`)
- Productos e inventario → DTO y mappers: convierte datos (evidence: `src/main/java/ec/edu/espe/ventas/service/ProductoService.java`)
- Ventas y stock → DTO y mappers: produce respuestas (evidence: `src/main/java/ec/edu/espe/ventas/service/VentaService.java`)
- Consulta auditoría → Repositorio auditoría: consulta registros (evidence: `src/main/java/ec/edu/espe/ventas/service/AuditoriaService.java`)
- Auditoría AOP → Repositorio auditoría: guarda auditoría (evidence: `src/main/java/ec/edu/espe/ventas/aspect/AuditoriaAspect.java`)
- Repositorio auditoría → Modelo comercial: persiste auditoría (evidence: `src/main/java/ec/edu/espe/ventas/repository/AuditoriaRepository.java`)
- Auditoría AOP → Ventas y stock: intercepta @Auditable
- Errores HTTP → Cliente HTTP: devuelve error uniforme
