# yerridev/sistema-pos architecture

> Architecture diagram of the GitHub repository yerridev/sistema-pos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yerridev/sistema-pos
- Repository: https://github.com/yerridev/sistema-pos

## Overview

1. **Overall shape**
   - This is a **single Django monolith** split into domain apps, not a microservices system.
   - The core business areas are separated by app: `usuarios`, `productos`, `ventas`, `caja`, `compras`, and `reportes`.
   - All apps share one database and are wired together through Django’s project config in `config/`.

2. **Runtime and deployment boundary**
   - The project runs as a standard Django stack with `manage.py`, plus `config/asgi.py` and `config/wsgi.py` for app serving.
   - `docker-compose.yml` and `Dockerfile` show a containerized deployment, with Django as the web container and PostgreSQL as the backing datastore.
   - Environment settings come from `.env`, so runtime configuration is externalized rather than hardcoded.

3. **Request entry points**
   - `config/urls.py` is the central router that delegates requests into the domain apps.
   - The repository exposes both **API endpoints** and at least one **server-rendered page**: `templates/login.html`.
   - The auth surface is explicitly documented around `/api/token/`, `/api/token/refresh/`, `/login/`, and the API docs endpoints.

4. **Authentication and identity**
   - `usuarios/` is the authentication and identity boundary for the system.
   - It contains `auth_views.py`, `serializers.py`, and `views.py`, which suggests it owns login/token flow and API-facing user data handling.
   - The README indicates JWT-based auth with role claims for **admin**, **cajero**, and **supervisor**, which drives access control throughout the rest of the system.

5. **Sales and cashiering flow**
   - `ventas/` is the transactional core for point-of-sale operations.
   - A sale likely aggregates sale header data plus line items, and the README confirms the sale flow updates **stock** and interacts with **cashbox state**.
   - This module is the main business boundary for checkout, ticket generation, and payment-method handling.

6. **Cashbox management**
   - `caja/` owns opening/closing a cash register session and tracking movements.
   - It is tightly coupled to `ventas/` because sales must occur against an open cashbox, and closing a box depends on accumulated transactions.
   - This app is the source of reconciliation data used for end-of-day balancing and difference calculation.

7. **Inventory and product catalog**
   - `productos/` owns the product master data and stock control.
   - The README describes product fields such as barcode, sale price, cost, current stock, minimum stock, category, and unit, which makes this the inventory source of truth.
   - This module feeds both sales validation and low-stock alerts.

8. **Purchasing and stock replenishment**
   - `compras/` handles supplier-based purchases and inventory inflow.
   - Purchase registration updates stock automatically, so this app is one of the main write paths into inventory.
   - Conceptually, it is the upstream replenishment flow that balances the downstream depletion caused by sales.

9. **Reporting and read-only analytics**
   - `reportes/` is a read-optimized boundary that derives operational metrics from the transactional apps.
   - The README mentions daily sales, payment-method totals, top products, critical stock, and profit/utilidad reports.
   - This module should be thought of as consuming data from `ventas`, `caja`, `compras`, and `productos` rather than owning primary business state.

10. **Data persistence and schema lifecycle**
   - Each app has its own `models.py` and `migrations/`, so the schema is managed per domain but deployed together.
   - `admin.py` files across apps indicate Django Admin is used as an internal management surface for CRUD and operational oversight.
   - `tests.py` in every app shows the repository is organized around per-domain test coverage, which matches the modular business layout.

11. **Architecture summary for a diagram**
   - Draw one central **Django application layer** split into six domain modules.
   - Show **users/auth** at the edge issuing JWTs and enforcing roles.
   - Show **ventas** and **caja** as tightly coupled transactional flows.
   - Show **compras** feeding **productos/stock**.
   - Show **reportes** as a read-only consumer of the transactional domains.
   - Place **PostgreSQL** as the shared persistence layer and **Docker Compose** as the local orchestration boundary.

Main entry points: [`config/urls.py`](https://github.com/yerridev/sistema-pos/blob/main/config/urls.py) (Router), [`reportes/views.py`](https://github.com/yerridev/sistema-pos/blob/main/reportes/views.py) (Analytics), [`productos/models.py`](https://github.com/yerridev/sistema-pos/blob/main/productos/models.py) (Catalog), [`manage.py`](https://github.com/yerridev/sistema-pos/blob/main/manage.py) (manage.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_manage["manage.py<br/>django launcher<br/>[manage.py]"]
  node_settings["Settings<br/>project config<br/>[settings.py]"]
  node_urls["Router<br/>url conf<br/>[urls.py]"]
  node_asgi["ASGI<br/>app server<br/>[asgi.py]"]
  node_wsgi["WSGI<br/>app server<br/>[wsgi.py]"]
  node_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_dockerfile["Dockerfile<br/>image build"]
  node_login["Login page<br/>template<br/>[login.html]"]
end

subgraph group_domains["Domain apps"]
  node_usuarios_app["Users<br/>auth boundary<br/>[models.py]"]
  node_usuarios_auth["Auth views<br/>jwt endpoints<br/>[auth_views.py]"]
  node_usuarios_data["Serializers<br/>api schema<br/>[serializers.py]"]
  node_productos_app["Catalog<br/>inventory domain<br/>[models.py]"]
  node_ventas_app["Sales<br/>pos domain<br/>[models.py]"]
  node_caja_app["Cashbox<br/>reconciliation domain<br/>[models.py]"]
  node_compras_app["Purchases<br/>procurement domain<br/>[models.py]"]
  node_reportes_app["Reports<br/>analytics domain<br/>[models.py]"]
  node_ventas_views["Checkout<br/>sale workflow<br/>[views.py]"]
  node_caja_views["Reconcile<br/>cashbox workflow<br/>[views.py]"]
  node_productos_views["Catalog ops<br/>inventory workflow<br/>[views.py]"]
  node_compras_views["Purchasing<br/>procurement workflow<br/>[views.py]"]
  node_reportes_views["Analytics<br/>reporting workflow<br/>[views.py]"]
end

subgraph group_data["Data"]
  node_env["Env<br/>runtime config<br/>[.env.example]"]
  node_db[("PostgreSQL<br/>shared database")]
end

node_manage -->|"boots"| node_settings
node_manage -->|"routes"| node_urls
node_manage -->|"serves"| node_asgi
node_manage -->|"serves"| node_wsgi
node_compose -->|"builds"| node_dockerfile
node_compose -->|"provisions"| node_db
node_compose -->|"configures"| node_settings
node_settings -->|"reads"| node_env
node_settings -->|"connects"| node_db
node_urls -->|"auth routes"| node_usuarios_auth
node_urls -->|"user routes"| node_usuarios_app
node_urls -->|"sales routes"| node_ventas_views
node_urls -->|"cash routes"| node_caja_views
node_urls -->|"catalog routes"| node_productos_views
node_urls -->|"purchase routes"| node_compras_views
node_urls -->|"report routes"| node_reportes_views
node_usuarios_auth -->|"renders"| node_login
node_usuarios_auth -->|"uses"| node_usuarios_data
node_ventas_views -->|"writes"| node_ventas_app
node_ventas_views -->|"checks stock"| node_productos_app
node_ventas_views -->|"posts movement"| node_caja_app
node_caja_views -->|"updates"| node_caja_app
node_caja_views -->|"consumes"| node_ventas_app
node_productos_views -->|"maintains"| node_productos_app
node_compras_views -->|"replenishes"| node_productos_app
node_reportes_views -->|"reads"| node_ventas_app
node_reportes_views -->|"reads"| node_caja_app
node_reportes_views -->|"reads"| node_compras_views
node_reportes_views -->|"reads"| node_productos_app
node_usuarios_app -->|"persists"| node_db
node_productos_app -->|"persists"| node_db
node_ventas_app -->|"persists"| node_db
node_caja_app -->|"persists"| node_db
node_compras_app -->|"persists"| node_db
node_reportes_app -->|"reads"| node_db

click node_manage "https://github.com/yerridev/sistema-pos/blob/main/manage.py"
click node_settings "https://github.com/yerridev/sistema-pos/blob/main/config/settings.py"
click node_urls "https://github.com/yerridev/sistema-pos/blob/main/config/urls.py"
click node_asgi "https://github.com/yerridev/sistema-pos/blob/main/config/asgi.py"
click node_wsgi "https://github.com/yerridev/sistema-pos/blob/main/config/wsgi.py"
click node_compose "https://github.com/yerridev/sistema-pos/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/yerridev/sistema-pos/tree/main/Dockerfile"
click node_env "https://github.com/yerridev/sistema-pos/blob/main/.env.example"
click node_login "https://github.com/yerridev/sistema-pos/blob/main/templates/login.html"
click node_usuarios_app "https://github.com/yerridev/sistema-pos/blob/main/usuarios/models.py"
click node_usuarios_auth "https://github.com/yerridev/sistema-pos/blob/main/usuarios/auth_views.py"
click node_usuarios_data "https://github.com/yerridev/sistema-pos/blob/main/usuarios/serializers.py"
click node_productos_app "https://github.com/yerridev/sistema-pos/blob/main/productos/models.py"
click node_ventas_app "https://github.com/yerridev/sistema-pos/blob/main/ventas/models.py"
click node_caja_app "https://github.com/yerridev/sistema-pos/blob/main/caja/models.py"
click node_compras_app "https://github.com/yerridev/sistema-pos/blob/main/compras/models.py"
click node_reportes_app "https://github.com/yerridev/sistema-pos/blob/main/reportes/models.py"
click node_ventas_views "https://github.com/yerridev/sistema-pos/blob/main/ventas/views.py"
click node_caja_views "https://github.com/yerridev/sistema-pos/blob/main/caja/views.py"
click node_productos_views "https://github.com/yerridev/sistema-pos/blob/main/productos/views.py"
click node_compras_views "https://github.com/yerridev/sistema-pos/blob/main/compras/views.py"
click node_reportes_views "https://github.com/yerridev/sistema-pos/blob/main/reportes/views.py"

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_manage,node_settings,node_urls,node_asgi,node_wsgi,node_compose,node_dockerfile,node_login toneBlue
class node_usuarios_app,node_usuarios_auth,node_usuarios_data,node_productos_app,node_ventas_app,node_caja_app,node_compras_app,node_reportes_app,node_ventas_views,node_caja_views,node_productos_views,node_compras_views,node_reportes_views toneAmber
class node_env,node_db toneMint
```

## Components

### Runtime

Django entrypoints and containerization

- [manage.py](https://github.com/yerridev/sistema-pos/blob/main/manage.py): django launcher · Command-line entrypoint for the Django project · `manage.py`
- [Settings](https://github.com/yerridev/sistema-pos/blob/main/config/settings.py): project config · Central Django configuration and environment wiring · `config/settings.py`
- [Router](https://github.com/yerridev/sistema-pos/blob/main/config/urls.py): url conf · Main request router that delegates into domain apps · `config/urls.py`
- [ASGI](https://github.com/yerridev/sistema-pos/blob/main/config/asgi.py): app server · Async serving entrypoint · `config/asgi.py`
- [WSGI](https://github.com/yerridev/sistema-pos/blob/main/config/wsgi.py): app server · Sync serving entrypoint · `config/wsgi.py`
- [Compose](https://github.com/yerridev/sistema-pos/blob/main/docker-compose.yml): deployment · Local container orchestration for app and database · `docker-compose.yml`
- [Dockerfile](https://github.com/yerridev/sistema-pos/tree/main/Dockerfile): image build · Container image definition for the Django app · `Dockerfile`
- [Login page](https://github.com/yerridev/sistema-pos/blob/main/templates/login.html): template · Server-rendered login surface · `templates/login.html`

### Domain apps

Business modules in the monolith

- [Users](https://github.com/yerridev/sistema-pos/blob/main/usuarios/models.py): auth boundary · Identity, JWT issuance, and role-aware user data · `usuarios/models.py`
- [Auth views](https://github.com/yerridev/sistema-pos/blob/main/usuarios/auth_views.py): jwt endpoints · Token and login flow handling · `usuarios/auth_views.py`
- [Serializers](https://github.com/yerridev/sistema-pos/blob/main/usuarios/serializers.py): api schema · User-facing API representations and validation · `usuarios/serializers.py`
- [Catalog](https://github.com/yerridev/sistema-pos/blob/main/productos/models.py): inventory domain · Product master data and stock source of truth · `productos/models.py`
- [Sales](https://github.com/yerridev/sistema-pos/blob/main/ventas/models.py): pos domain · Checkout, ticketing, and sale transactions · `ventas/models.py`
- [Cashbox](https://github.com/yerridev/sistema-pos/blob/main/caja/models.py): reconciliation domain · Open/close sessions and cash movements · `caja/models.py`
- [Purchases](https://github.com/yerridev/sistema-pos/blob/main/compras/models.py): procurement domain · Supplier purchases and stock replenishment · `compras/models.py`
- [Reports](https://github.com/yerridev/sistema-pos/blob/main/reportes/models.py): analytics domain · Read-optimized operational metrics and summaries · `reportes/models.py`
- [Checkout](https://github.com/yerridev/sistema-pos/blob/main/ventas/views.py): sale workflow · Sale processing and payment flow · `ventas/views.py`
- [Reconcile](https://github.com/yerridev/sistema-pos/blob/main/caja/views.py): cashbox workflow · Opening, closing, and balancing operations · `caja/views.py`
- [Catalog ops](https://github.com/yerridev/sistema-pos/blob/main/productos/views.py): inventory workflow · Product and stock management actions · `productos/views.py`
- [Purchasing](https://github.com/yerridev/sistema-pos/blob/main/compras/views.py): procurement workflow · Purchase registration and inventory inflow · `compras/views.py`
- [Analytics](https://github.com/yerridev/sistema-pos/blob/main/reportes/views.py): reporting workflow · Operational reports derived from transactional data · `reportes/views.py`

### Data

Shared persistence and externalized config

- [Env](https://github.com/yerridev/sistema-pos/blob/main/.env.example): runtime config · Example external configuration for secrets and settings · `.env.example`
- **PostgreSQL**: shared database · Single backing datastore for all domain apps

## Connections

- manage.py → Settings: boots · Loads project configuration
- manage.py → Router: routes · Starts request routing
- manage.py → ASGI: serves · ASGI deployment entrypoint
- manage.py → WSGI: serves · WSGI deployment entrypoint
- Compose → Dockerfile: builds · Uses the app image definition
- Compose → PostgreSQL: provisions · Starts the shared PostgreSQL service
- Compose → Settings: configures · Supplies runtime environment to Django
- Settings → Env: reads · Externalizes secrets and settings
- Settings → PostgreSQL: connects · Binds the monolith to the shared database
- Router → Auth views: auth routes · Delegates login and token endpoints
- Router → Users: user routes · Delegates identity-related API surfaces
- Router → Checkout: sales routes · Delegates checkout endpoints
- Router → Reconcile: cash routes · Delegates cashbox endpoints
- Router → Catalog ops: catalog routes · Delegates product and stock endpoints
- Router → Purchasing: purchase routes · Delegates procurement endpoints
- Router → Analytics: report routes · Delegates reporting endpoints
- Auth views → Login page: renders · Serves the login page
- Auth views → Serializers: uses · Validates and serializes auth payloads
- Checkout → Sales: writes · Persists sales and line items
- Checkout → Catalog: checks stock · Validates and decrements inventory
- Checkout → Cashbox: posts movement · Records cashbox impacts of sales
- Reconcile → Cashbox: updates · Opens, closes, and reconciles sessions
- Reconcile → Sales: consumes · Uses sale totals for balancing
- Catalog ops → Catalog: maintains · Manages catalog and stock data
- Purchasing → Catalog: replenishes · Adds inventory from purchases
- Analytics → Sales: reads · Derives sales metrics
- Analytics → Cashbox: reads · Derives cashbox metrics
- Analytics → Purchasing: reads · Uses purchase activity as reporting input
- Analytics → Catalog: reads · Derives stock and top-product metrics
- Users → PostgreSQL: persists · Shares the central datastore
- Catalog → PostgreSQL: persists · Shares the central datastore
- Sales → PostgreSQL: persists · Shares the central datastore
- Cashbox → PostgreSQL: persists · Shares the central datastore
- Purchases → PostgreSQL: persists · Shares the central datastore
- Reports → PostgreSQL: reads · Consumes the shared datastore for analytics
