How berprado/erpapi works
1. This repository is a single-deployment backend-plus-frontend system for POS inventory auditing. The FastAPI application serves both the REST API and the built-in PWA frontend, so the main architectural boundary is not “frontend vs backend repo,” but “browser/PWA client vs API vs MySQL database.”
2. The backend core is organized around four Python modules:
- main.py as the application entrypoint and route assembly point
- models.py for SQLAlchemy ORM mappings
- schemas.py for request/response validation via Pydantic
- database.py and config.py for DB connectivity and environment-driven settings
3. The frontend is a static PWA under static/ with index.html, app.js, sw.js, a manifest, and UI assets. It is not a separate SPA framework; it is vanilla JavaScript with service-worker caching and local autosave. The same backend process serves the UI and the API, which simplifies deployment and keeps the client/server contract tight.
4. Authentication and session control are centralized in the API using JWT. The login flow returns a token, and all business endpoints are protected by HTTP bearer auth. The repo also documents a SHA-256 password verification compatibility layer with the POS ecosystem, which is important because it constrains how user credentials are handled.
5. The operational gate is the “operativa” state in the database. Before inventory actions are allowed, the system validates that the active operation is in state 24 (INICIO CIERRE). This makes the operational state a key domain boundary: if the operation advances, paloteo editing and correction are blocked.
6. The main business subsystem is inventory paloteo. The frontend exposes PALOTEO 1, PALOTEO 2, PALOTEO 3, and REPORTE views, but they all write into one canonical inventory payload. The API endpoints support:
- listing pending products
- posting a full physical inventory
- reading an existing inventory by operation
- correcting selected items while preserving non-sent items
7. Product selection for paloteo is derived from operational data, not entered manually from scratch. The API combines products sold during the operation plus transfers from warehouse to bar, then applies per-product weighing configuration. This means the data flow is: operational transactions in MySQL → pending inventory list → captured physical counts → persisted inventory header/detail.
8. Weighable products have a dedicated subdomain and model layer. The API can create weighing profiles for bottle models, and the frontend validates bottle-related constraints before submission. The implementation stores both the exact raw ounce totals and the POS-facing rounded ounces, so the architecture explicitly separates audit precision from downstream POS compatibility.
9. The paloteo workflow also has a report/export subsystem. A request can generate a PDF report in memory, with variants for general, income, and salida views. The report export is tied to the filtered client-side view, so the UI state affects the generated document. Static PDF files in static/pdfs/ appear to be examples or generated outputs used alongside this feature.
10. Local persistence is part of the client architecture. The PWA autosaves drafts by operation, bar, and user, which reduces data loss during multi-step inventory capture. The service worker uses cache-first behavior for static assets and network-first for /api/*, so the app is designed to remain usable even with intermittent connectivity while keeping business data fresh.
11. Configuration is environment-based and split between test and production databases. APP_ENV switches between local WAMP/MySQL and remote production credentials, while additional flags control the “operativa bar” resolution. This makes deployment behavior a first-class architectural concern rather than hardcoded logic.
12. The database schema is centered on a small set of business tables: users and access logs, operations, weighed-product configuration, physical inventory headers and details, and raw weigh audit records. That table set reflects the main domain boundaries: identity, operation control, inventory capture, and audit traceability.
13. The documentos/ folder is not just documentation; it is architectural context. It contains implementation notes, comparative designs, and model discussions for paloteo, weighing, and report generation. For a diagram, this repository should be represented as a domain-specific operational system with a tightly coupled PWA client, a FastAPI service layer, and a MySQL-backed inventory/audit model.
Main entry points: main.py App entry · models.py ORM models · documentos Domain notes · app.js Client logic
Components 15
PWA client
Browser-facing static app and offline behavior.
- UI shell · Served HTML entrypoint for the built-in inventory app.
static/index.html - Client logic · PWA screens, forms, local autosave, and API calls.
static/app.js - Service worker · Cache-first static assets with network-first API handling.
static/sw.js - Manifest · Web app metadata for installable PWA behavior.
static/manifest.json
FastAPI service
Application entrypoint, auth, and business endpoints.
- App entry · Creates the application, assembles routes, and serves the UI/API.
main.py - Auth gate · Login, token issuance, password verification, and protected endpoints.
main.py - Paloteo flow · Pending products, full counts, correction, and operation-bound inventory reads.
main.py - Weighing · Bottle and weighable-product handling with precision and POS rounding.
main.py - Reports · Generates in-memory paloteo PDFs for general, income, and salida views.
main.py
Data model
Configuration, ORM, schemas, and MySQL persistence.
- Settings · Environment-driven database and deployment switches.
config.py - DB session · Database engine, connection, and session wiring.
database.py - ORM models · Users, operations, inventory headers/details, weights, and audit records.
models.py - API schemas · Request and response validation for the REST contract.
schemas.py - MySQL · Operational source of truth for users, operations, inventory, and auditability.
Docs
Repository documentation and implementation notes.
- Domain notes · Implementation context for paloteo, weighing, and report workflows.
documentos
Connections 21
- UI shell → Client logic: loads · The HTML shell bootstraps the client logic.
- Client logic → Service worker: registers · Client enables offline behavior through the service worker.
- Client logic → App entry: calls API · Browser actions post and fetch inventory data from the backend.
- Service worker → App entry: network-first /api · Business requests are refreshed from the API when possible.
- App entry → Auth gate: mounts · Application includes JWT login and bearer-protected routes.
- App entry → Paloteo flow: mounts · Application exposes the paloteo and correction endpoints.
- App entry → Weighing: mounts · Application exposes weighable-product configuration and validation flows.
- App entry → Reports: mounts · Application exposes PDF report generation.
- App entry → DB session: uses · Routes operate through the shared database session layer.
- DB session → Settings: reads settings · Connection setup depends on environment configuration.
- DB session → MySQL: connects to · Persistent state lives in MySQL.
- ORM models → MySQL: maps to · ORM models define the business tables in the database.
- API schemas → App entry: validates · Pydantic schemas shape incoming and outgoing API payloads.
- Paloteo flow → ORM models: writes/reads · Inventory operations persist headers, details, and corrections.
- Paloteo flow → API schemas: uses · Inventory endpoints exchange typed payloads.
- Weighing → ORM models: writes/reads · Weighing profiles and audit traces are persisted through ORM models.
- Reports → Paloteo flow: renders from · Reports are derived from the current paloteo data and filters.
- Auth gate → ORM models: checks users · Authentication depends on stored credentials and access logs.
- Domain notes → Paloteo flow: documents · Notes describe paloteo, correction, and operational state rules.
- Domain notes → Weighing: documents · Notes describe weighable-product behavior and bottle constraints.
- Domain notes → Reports: documents · Notes describe PDF export variants and view coupling.