How yerridev/sistema-pos works
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: urls.py Router · views.py Analytics · models.py Catalog · manage.py manage.py
Components 23
Runtime
Django entrypoints and containerization
- manage.py · Command-line entrypoint for the Django project
manage.py - Settings · Central Django configuration and environment wiring
config/settings.py - Router · Main request router that delegates into domain apps
config/urls.py - ASGI · Async serving entrypoint
config/asgi.py - WSGI · Sync serving entrypoint
config/wsgi.py - Compose · Local container orchestration for app and database
docker-compose.yml - Dockerfile · Container image definition for the Django app
Dockerfile - Login page · Server-rendered login surface
templates/login.html
Domain apps
Business modules in the monolith
- Users · Identity, JWT issuance, and role-aware user data
usuarios/models.py - Auth views · Token and login flow handling
usuarios/auth_views.py - Serializers · User-facing API representations and validation
usuarios/serializers.py - Catalog · Product master data and stock source of truth
productos/models.py - Sales · Checkout, ticketing, and sale transactions
ventas/models.py - Cashbox · Open/close sessions and cash movements
caja/models.py - Purchases · Supplier purchases and stock replenishment
compras/models.py - Reports · Read-optimized operational metrics and summaries
reportes/models.py - Checkout · Sale processing and payment flow
ventas/views.py - Reconcile · Opening, closing, and balancing operations
caja/views.py - Catalog ops · Product and stock management actions
productos/views.py - Purchasing · Purchase registration and inventory inflow
compras/views.py - Analytics · Operational reports derived from transactional data
reportes/views.py
Data
Shared persistence and externalized config
- Env · Example external configuration for secrets and settings
.env.example - PostgreSQL · Single backing datastore for all domain apps
Connections 35
- 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