Work detail

The problem

In many small and medium businesses, daily operations rely on:

• spreadsheets,
• disconnected tools,
• manual processes with no state control,
• and lack of a unified view of the business.

This leads to:

• duplicate data,
• loss of traceability,
• operational errors,
• and poor decision-making.

This backend was built to eliminate that fragmentation.

The solution

I designed a commercial management backend that acts as the single source of truth for purchases, sales, stock, and cash.

Layered architecture

The system implements clear separation of layers:

• controllers
• services
• mappers
• schemas

Each layer has explicit contracts and is documented.

Base model + extensions

One of the key lessons from this project is the use of a Base + specialization architecture:

• Base model
  • id
  • timestamps
  • status
  • to_dict()
• Business models extend from that base.

Other layers extend those models:

• BaseService
• BaseController
• BaseRouter

CRUD and workflows are built from there:

• create
• get_all
• get_by_id
• update
• delete (soft delete)
• restore

This allows the system to evolve without breaking contracts.

• coherent evolution
• easier maintenance
• higher decision capacity

Domain-driven structure

During development I discovered that I was naturally applying an informal DDD architecture:

• Entities
  • represent identity in the domain
  • contain business rules
  • prevent invalid states
  • are validated across layers
• Aggregates
  • define consistency boundaries
  • protect business invariants
  • control transaction scope
• Documents
  • represent business transactions
  • persist events
  • drive operational flows
  • connect entities and aggregates
• Events
  • capture transitions
  • trigger stock and cash movements

Documents are not just data: they represent actions that impact aggregates through events.

Main functionality

Commercial management

• purchases
• sales

Stock

• stock locations
• stock transfers
• stock valuation

Cash

• cash accounts
• cash transfers

Business documents

• Purchase delivery notes
• Sales delivery notes
• Confirmation of documents
• Explicit rules by state (DRAFT / CONFIRMED)

Security, roles and access control

• Authentication with login + JWT
• Role-based access control
• Automatic token invalidation after password change

Roles:

• ADMIN
  • full access
  • sensitive operations
  • configuration
• USER
  • limited operational access

Explicit security rules:

No hidden permissions or implicit logic.

Backups and data protection

Backup and recovery are part of the system:

• JSON exports
• data restore
• migration support

Designed to protect business continuity.

Tech stack

• Language: Python
• Framework: Flask (WSGI)
• Database: SQLite
• ORM: SQLAlchemy
• Authentication: JWT
• Testing: pytest, pytest-cov
• CORS: Flask-Cors
• Configuration: python-dotenv

Operations and deployment

• Backend deployed on PythonAnywhere
• Operational update documented in the repo
• SQLite database in production
• System running and publicly accessible

🔗 Production API

🔗 GitHub repository

Origins

This project is one of the first where I started to formalize the use of AI in development.

It started with:

• purchase documents
• sales documents
• stock movements
• cash movements
• basic invoicing

It then evolved into:

• a governed domain model
• documented processes
• explicit validation
• controlled operations

What this project proves

This project demonstrates my ability to:

• Design a governed backend for real business operations
• Implement layered architecture with explicit contracts
• Build traceability into every flow
• Enforce business rules with state-driven documents
• Operate a production system with reliability
• Maintain clean boundaries between technical layers

Project images