# 13felixlopez/sisventacontable architecture

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

- Interactive diagram: https://gitdiagram.com/13felixlopez/sisventacontable
- Repository: https://github.com/13felixlopez/sisventacontable

## Overview

1. **Project shape**
   - `SisVentaContable` is a classic **Windows Forms desktop app** on **.NET Framework 4.8**.
   - It is organized as a **three-layered client app**: UI forms at the top, business/data logic in `Logica/`, and domain entities in `Modelo/`.
   - Persistence is externalized to **SQL Server** via `System.Data.SqlClient`; the app depends heavily on stored procedures and table-valued parameters.

2. **Startup and application shell**
   - Execution starts in `Program.cs`, which opens `Login`.
   - After authentication, the app loads `Form1` as the **MDI main container**, where operational modules are launched.
   - `Form1` also handles visual theme application, role-based menu access, and operational alerts.

3. **Primary runtime boundary: UI vs business logic**
   - The WinForms layer (`frmVenta`, `frmCompra`, `frmReporte`, `frmGestion`, etc.) collects user input and drives workflows.
   - The `Logica/` layer encapsulates database calls, usually per domain area:
     - `VentaLogica`, `CompraLogica`, `CajaLogica`, `AbonosLogica`, `ProductoLogica`, `PersonaLogica`, etc.
   - The `Modelo/` layer defines the data contract used across forms and logic, such as `Venta`, `Compra`, `Producto`, `Persona`, `Caja`, `DetalleVenta`, and `DetalleCompra`.

4. **Authentication and operational gating**
   - `Login.cs` is not just credential entry; it also enforces **daily cashbox state** before the user can enter the system.
   - It checks whether there is an open cash session, whether the previous one was left open, and whether the day is already closed.
   - Access control is role-aware: users are validated against the `Persona` model and roles are used to restrict features in the main menu.

5. **Sales subsystem**
   - `frmVenta` and `VentaLogica` implement the core sales flow: product selection, client selection, calculation of totals, stock validation, and final registration.
   - Sales can be **cash, credit, or proforma**.
   - Registration is batch-oriented: the app sends a structured detail set to SQL Server via `sp_RegistrarVenta`, then prints an HTML ticket from `Resources/Ticket*.html`.
   - The subsystem also supports **returns/devolutions**, likely as a separate stored-procedure-driven transaction.

6. **Purchasing and inventory replenishment**
   - `frmCompra` and `CompraLogica` handle purchase entry with supplier, document, payment method, and line-item details.
   - Purchases update **stock and costs** through the database transaction, with `sp_RegistrarCompraCompleta` as the central operation.
   - This flow is tightly coupled to inventory updates, so purchase completion is an important state transition for the product catalog.

7. **Cash management / daily arqueo**
   - `frmAperturaCaja` and `frmCierreCaja`, backed by `CajaLogica`, manage the day’s cashbox lifecycle.
   - The app records opening balance, closing observations, and movements such as incomes, expenses, and adjustments.
   - Sales, purchases, and manual operations feed into cash movements; this subsystem is the operational accounting backbone of the app.

8. **Credit and collections**
   - `Abonos.cs` and `AbonosLogica` implement customer credit tracking and payment collection.
   - The flow reads current debt, total paid, and pending balance, then records an abono.
   - After payment, the app can generate an HTML receipt (`Resources/facturaabono.html`) and optionally trigger SMS notification, including phone-number correction if the customer contact data changed.

9. **Master data and administration**
   - Separate CRUD forms manage the main business entities:
     - `frmCliente` / `PersonaLogica`
     - `frmProveedor` / `ProveedorLogica`
     - `frmUsuario`
     - product/category/unit maintenance through product-related logic classes
   - `frmGestion` acts as the administrative hub for catalog configuration, store metadata, theme settings, and integration settings.
   - `ModalPersona`, `ModalProducto`, `ModalProveedor`, and `ModalSeleccionUnidad` support selection/editing from transactional screens.

10. **Reporting and exports**
   - `frmReporte` is the reporting surface for sales, sales detail, purchases, cash movements, credits, and expenses over date ranges.
   - Reporting is SQL-driven and includes totals and filtering by operation type.
   - The project includes Excel export dependencies, so reporting is not just on-screen; it can be moved into spreadsheet output.

11. **External integrations and side services**
   - `TelegramNotificacionService` sends operational notifications for sales/purchases, with configuration stored locally.
   - `SmsGatewayService` is used specifically around credit collections/abonos, with support for local/cloud modes and endpoint normalization.
   - These integrations are **asynchronous side effects** attached to transactional events, not core to transaction success.

12. **Configuration, security, and persistence of secrets**
   - Connection settings are managed through `frmConfiguracionConexion`, with AES-based protection in `Funciones/AES.cs` and `Desencryptacion.cs`.
   - The app stores local preferences and integration credentials in `Properties.Settings`, while the SQL connection is persisted separately in `ConnectionString.xml`.
   - This creates a clear split between **operational configuration** (theme, Telegram, SMS, exchange rate) and **database connectivity**.

13. **Utility and batch-processing boundary**
   - `Funciones/CargaMasiva.cs` provides Excel-based bulk import, specifically for suppliers, using a validation-and-progress workflow.
   - `UiHelper.cs`, `Log.cs`, and related helpers support non-domain concerns such as UI behavior, logging, encryption, and connection security.
   - These utilities are supportive rather than business-critical, but they matter because they shape user experience and deployment setup.

14. **Overall data flow for the diagram**
   - User action enters through WinForms UI.
   - The UI calls into a corresponding logic class.
   - The logic layer reads/writes SQL Server using stored procedures and entity models.
   - Transactional workflows then fan out to side effects: ticket generation, Telegram/SMS notifications, report generation, and cashbox updates.
   - The key architectural boundary is that **business state lives in SQL Server**, while the desktop app orchestrates workflows, validation, and presentation.

Main entry points: [`SisVentaContable/Form1.cs`](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Form1.cs) (Main shell), [`SisVentaContable/Modelo/Venta.cs`](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Modelo/Venta.cs) (Entities), [`SisVentaContable/Logica/VentaLogica.cs`](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/VentaLogica.cs) (VentaLogica), [`SisVentaContable/Logica/AbonosLogica.cs`](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/AbonosLogica.cs) (AbonosLogica)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI shell"]
  node_program["Program<br/>startup<br/>[Program.cs]"]
  node_login["Login<br/>auth screen<br/>[Login.cs]"]
  node_main_shell["Main shell<br/>mdi host<br/>[Form1.cs]"]
  node_sales_form["Ventas<br/>sales form<br/>[frmVenta.cs]"]
  node_purchase_form["Compras<br/>purchase form<br/>[frmCompra.cs]"]
  node_cash_open_close["Caja<br/>cash forms<br/>[frmAperturaCaja.cs]"]
  node_collections["Abonos<br/>collections form<br/>[Abonos.cs]"]
  node_reports["Reportes<br/>reporting form<br/>[frmReporte.cs]"]
  node_admin_hub["Gestión<br/>admin hub<br/>[frmGestion.cs]"]
  node_personas["Personas<br/>master data<br/>[frmCliente.cs]"]
  node_proveedores["Proveedores<br/>master data<br/>[frmProveedor.cs]"]
end

subgraph group_logic["Business logic"]
  node_venta_logic["VentaLogica<br/>sales logic<br/>[VentaLogica.cs]"]
  node_compra_logic["CompraLogica<br/>purchase logic<br/>[CompraLogica.cs]"]
  node_caja_logic["CajaLogica<br/>cash logic<br/>[CajaLogica.cs]"]
  node_abonos_logic["AbonosLogica<br/>collections logic<br/>[AbonosLogica.cs]"]
  node_producto_persona_logic["Catálogo logic<br/>catalog logic<br/>[ProductoLogica.cs]"]
end

subgraph group_model["Domain model"]
  node_domain_model["Entities<br/>domain model<br/>[Venta.cs]"]
end

subgraph group_infra["Infrastructure"]
  node_sql_layer[("SQL Server<br/>database")]
  node_notifiers["Notifiers<br/>integrations"]
  node_security_config["Security & config<br/>infra support"]
  node_bulk_import["Bulk import<br/>excel import<br/>[CargaMasiva.cs]"]
end

node_program -->|"starts"| node_login
node_login -->|"checks cashbox"| node_caja_logic
node_login -->|"opens"| node_main_shell
node_main_shell -->|"launches"| node_sales_form
node_main_shell -->|"launches"| node_purchase_form
node_main_shell -->|"launches"| node_cash_open_close
node_main_shell -->|"launches"| node_collections
node_main_shell -->|"launches"| node_reports
node_main_shell -->|"launches"| node_admin_hub
node_main_shell -->|"launches"| node_personas
node_main_shell -->|"launches"| node_proveedores
node_sales_form -->|"uses"| node_venta_logic
node_purchase_form -->|"uses"| node_compra_logic
node_cash_open_close -->|"uses"| node_caja_logic
node_collections -->|"uses"| node_abonos_logic
node_personas -->|"uses"| node_producto_persona_logic
node_proveedores -->|"uses"| node_producto_persona_logic
node_venta_logic -->|"maps"| node_domain_model
node_compra_logic -->|"maps"| node_domain_model
node_caja_logic -->|"maps"| node_domain_model
node_abonos_logic -->|"maps"| node_domain_model
node_producto_persona_logic -->|"maps"| node_domain_model
node_venta_logic -->|"persists"| node_sql_layer
node_compra_logic -->|"persists"| node_sql_layer
node_caja_logic -->|"persists"| node_sql_layer
node_abonos_logic -->|"persists"| node_sql_layer
node_producto_persona_logic -->|"persists"| node_sql_layer
node_reports -->|"queries"| node_sql_layer
node_venta_logic -.->|"triggers"| node_notifiers
node_abonos_logic -.->|"triggers"| node_notifiers
node_admin_hub -->|"configures"| node_security_config
node_security_config -->|"connects"| node_sql_layer
node_admin_hub -->|"imports"| node_bulk_import
node_security_config -->|"configures"| node_notifiers

click node_program "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Program.cs"
click node_login "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Login.cs"
click node_main_shell "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Form1.cs"
click node_sales_form "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmVenta.cs"
click node_purchase_form "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmCompra.cs"
click node_cash_open_close "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmAperturaCaja.cs"
click node_collections "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Abonos.cs"
click node_reports "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmReporte.cs"
click node_admin_hub "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmGestion.cs"
click node_personas "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmCliente.cs"
click node_proveedores "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmProveedor.cs"
click node_venta_logic "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/VentaLogica.cs"
click node_compra_logic "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/CompraLogica.cs"
click node_caja_logic "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/CajaLogica.cs"
click node_abonos_logic "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/AbonosLogica.cs"
click node_producto_persona_logic "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/ProductoLogica.cs"
click node_notifiers "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Funciones/TelegramNotificacionService.cs"
click node_security_config "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Funciones/frmConfiguracionConexion.cs"
click node_bulk_import "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Funciones/CargaMasiva.cs"
click node_domain_model "https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Modelo/Venta.cs"

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_program,node_login,node_main_shell,node_sales_form,node_purchase_form,node_cash_open_close,node_collections,node_reports,node_admin_hub,node_personas,node_proveedores toneBlue
class node_venta_logic,node_compra_logic,node_caja_logic,node_abonos_logic,node_producto_persona_logic toneAmber
class node_domain_model toneMint
class node_sql_layer,node_notifiers,node_security_config,node_bulk_import toneRose
```

## Components

### UI shell

WinForms entry points, module forms, and dialogs

- [Program](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Program.cs): startup · Application entry point that launches login flow · `SisVentaContable/Program.cs`
- [Login](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Login.cs): auth screen · Authenticates users and gates access by cashbox state · `SisVentaContable/Login.cs`
- [Main shell](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Form1.cs): mdi host · MDI container for operational modules, themes, menus, and alerts · `SisVentaContable/Form1.cs`
- [Ventas](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmVenta.cs): sales form · Sales workflow for products, clients, totals, and checkout · `SisVentaContable/frmVenta.cs`
- [Compras](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmCompra.cs): purchase form · Purchase entry and inventory replenishment workflow · `SisVentaContable/frmCompra.cs`
- [Caja](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmAperturaCaja.cs): cash forms · Daily cashbox opening and closing screens · `SisVentaContable/frmAperturaCaja.cs`
- [Abonos](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Abonos.cs): collections form · Credit tracking, payments, and receipt generation · `SisVentaContable/Abonos.cs`
- [Reportes](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmReporte.cs): reporting form · Operational reporting over sales, purchases, cash, and credits · `SisVentaContable/frmReporte.cs`
- [Gestión](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmGestion.cs): admin hub · Catalog, store, theme, and integration settings hub · `SisVentaContable/frmGestion.cs`
- [Personas](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmCliente.cs): master data · Customer and person maintenance screens · `SisVentaContable/frmCliente.cs`
- [Proveedores](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/frmProveedor.cs): master data · Supplier maintenance screens · `SisVentaContable/frmProveedor.cs`

### Business logic

Domain-focused orchestration and SQL access

- [VentaLogica](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/VentaLogica.cs): sales logic · Registers sales, validates stock, and coordinates ticket output · `SisVentaContable/Logica/VentaLogica.cs`
- [CompraLogica](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/CompraLogica.cs): purchase logic · Registers purchases and updates stock/costs · `SisVentaContable/Logica/CompraLogica.cs`
- [CajaLogica](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/CajaLogica.cs): cash logic · Manages cashbox lifecycle and movements · `SisVentaContable/Logica/CajaLogica.cs`
- [AbonosLogica](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/AbonosLogica.cs): collections logic · Tracks debt, records payments, and supports receipts · `SisVentaContable/Logica/AbonosLogica.cs`
- [Catálogo logic](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Logica/ProductoLogica.cs): catalog logic · Product, category, unit, person, supplier, and store operations · `SisVentaContable/Logica/ProductoLogica.cs`

### Domain model

Shared entities passed across forms and logic

- [Entities](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Modelo/Venta.cs): domain model · Shared contracts such as Venta, Compra, Producto, Persona, Caja, and details · `SisVentaContable/Modelo/Venta.cs`

### Infrastructure

Persistence, configuration, utilities, and external side effects

- **SQL Server**: database · Stored-procedure-driven persistence for business state
- [Notifiers](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Funciones/TelegramNotificacionService.cs): integrations · Telegram and SMS side-effect services for operational events · `SisVentaContable/Funciones/TelegramNotificacionService.cs`
- [Security & config](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Funciones/frmConfiguracionConexion.cs): infra support · Connection settings, encryption, settings storage, and UI helpers · `SisVentaContable/Funciones/frmConfiguracionConexion.cs`
- [Bulk import](https://github.com/13felixlopez/sisventacontable/blob/master/SisVentaContable/Funciones/CargaMasiva.cs): excel import · Excel-based supplier import workflow with validation and progress · `SisVentaContable/Funciones/CargaMasiva.cs`

## Connections

- Program → Login: starts · Application boots into authentication
- Login → CajaLogica: checks cashbox · Enforces daily cash session state before entry
- Login → Main shell: opens · Successful authentication loads the main MDI shell
- Main shell → Ventas: launches · Main menu opens the sales module
- Main shell → Compras: launches · Main menu opens the purchasing module
- Main shell → Caja: launches · Main menu opens cash opening/closing screens
- Main shell → Abonos: launches · Main menu opens credit collection workflows
- Main shell → Reportes: launches · Main menu opens reporting surface
- Main shell → Gestión: launches · Main menu opens administration and settings
- Main shell → Personas: launches · Main menu opens customer/person management
- Main shell → Proveedores: launches · Main menu opens supplier management
- Ventas → VentaLogica: uses · UI delegates sales workflow to business logic
- Compras → CompraLogica: uses · UI delegates purchase workflow to business logic
- Caja → CajaLogica: uses · Cash forms orchestrate opening and closing operations
- Abonos → AbonosLogica: uses · Collections UI delegates debt and payment handling
- Personas → Catálogo logic: uses · Master data screens rely on catalog logic
- Proveedores → Catálogo logic: uses · Supplier maintenance relies on catalog logic
- VentaLogica → Entities: maps · Sales logic exchanges Venta and DetalleVenta entities
- CompraLogica → Entities: maps · Purchase logic exchanges Compra and DetalleCompra entities
- CajaLogica → Entities: maps · Cash logic exchanges Caja and ArqueoCaja entities
- AbonosLogica → Entities: maps · Collections logic exchanges DAbonos and Persona entities
- Catálogo logic → Entities: maps · Catalog logic exchanges Producto, Persona, Proveedor, and related entities
- VentaLogica → SQL Server: persists · Sales are registered through stored procedures and TVPs
- CompraLogica → SQL Server: persists · Purchases are committed through database transactions
- CajaLogica → SQL Server: persists · Cash movements and openings/closings are stored in SQL Server
- AbonosLogica → SQL Server: persists · Payments and debt updates are written to SQL Server
- Catálogo logic → SQL Server: persists · Catalog maintenance reads and writes via SQL Server
- Reportes → SQL Server: queries · Reporting is driven by SQL queries and aggregates
- VentaLogica → Notifiers: triggers · Sales can fan out to Telegram or ticket output side effects
- AbonosLogica → Notifiers: triggers · Collections can trigger SMS notifications and receipt output
- Gestión → Security & config: configures · Administration manages connection, theme, and integration settings
- Security & config → SQL Server: connects · Connection configuration feeds database access
- Gestión → Bulk import: imports · Administration supports bulk supplier loading from Excel
- Security & config → Notifiers: configures · Local settings hold integration credentials and endpoints
