Skip to main content

​
Overview

The Solicitud Transporte API is built using a modern, layered architecture pattern that separates concerns and enables maintainability and scalability. The system manages transportation requests and missions for the ONI Justicia organization. System Architecture Overview

​
Technology Stack

FastAPI

Modern Python web framework for building APIs with automatic OpenAPI documentation

SQL Server

Primary relational database for transactional data using pymssql driver

MongoDB

NoSQL database for logging and flexible document storage using pymongo

​
Application Layers

The application follows a clean, layered architecture:

​
1. Router Layer (routers/)

The router layer handles HTTP requests and responses. Each router corresponds to a specific resource or domain entity.
  • Request validation using Pydantic models
  • HTTP endpoint definition and routing
  • Response formatting and status codes
  • Authentication and authorization (future)
Example routers:
  • solicitud_router.py - Transport request management (main.py:31)
  • mision_router.py - Mission operations (main.py:33)
  • vehiculo_router.py - Vehicle catalog (main.py:29)
  • motorista_router.py - Driver management (main.py:30)

​
2. Service Layer (services/)

The service layer contains the business logic and orchestrates operations across multiple data sources. 
class BaseService:
    """Base class for all services"""
    
    def __init__(self):
        self.db = get_sql_manager()
    
    def _serializar_valor(self, valor: Any) -> Any:
        """Converts Python types to JSON-serializable formats"""
        # Handles datetime, date, time, Decimal, bytes
        pass
All services inherit from BaseService which provides common utilities for database access and data serialization (services/base_service.py:14)

​
3. Database Layer (database/)

Provides abstraction for database operations with connection pooling and error handling.
File: database/sql_connection.pyThe SQLServerManager class provides:
  • Connection pooling via context managers (sql_connection.py:68)
  • Parameterized queries to prevent SQL injection (sql_connection.py:107)
  • Automatic commit/rollback handling (sql_connection.py:184)
  • CRUD helper methods (sql_connection.py:346)
# Connection configuration from config.py
server = settings.sqlserver.HOST
port = settings.sqlserver.PORT  # Default: 1433
database = settings.sqlserver.NAME

​
4. Model Layer (models/)

Pydantic models define the data structure and validation rules for API requests and responses.

Request Models

  • EstadoSolicitudCreate (estado_solicitud_model.py:16)
  • EstadoSolicitudUpdate (estado_solicitud_model.py:92)
  • Validation decorators for business rules

Response Models

  • EstadoSolicitudResponse (estado_solicitud_model.py:133)
  • EstadoSolicitudListResponse (estado_solicitud_model.py:151)
  • Automatic serialization of database types

​
Database Design

The system uses a normalized relational database schema with the following key tables:

​
Core Tables

Primary table for transportation requests (DevSolicitudTransporte:372)Key Fields:
  • CodigoSolicitud - Auto-generated code (SOL-YYYY-MM-########)
  • IdUsuarioSolicitante - Requesting user
  • IdDepartamentoSolicitante - Requesting department
  • IdUsuarioAprobador - Approving authority
  • FechaServicioRequerido - Required service date
  • HoraServicioRequerido - Required service time
  • IdEstadoSolicitud - Current state (FK)
Relationships:
  • One-to-many with Mision (missions)
  • One-to-many with HistoricoEstadoSolicitud (state history)
  • One-to-many with DetalleLugarSolicitud (locations)
Represents actual transportation assignments (DevSolicitudTransporte:523)Key Fields:
  • IdSolicitud - Parent request
  • IdVehiculoAsignado - Assigned vehicle
  • IdMotoristaAsignado - Assigned driver
  • IdLugarOrigen / IdLugarDestino - Origin/destination
  • FechaProgramada - Scheduled date
  • KilometrajeInicio / KilometrajeFin - Odometer readings
  • CombustibleConsumidoGalones - Fuel consumption
Catalog of possible request states (DevSolicitudTransporte:35)Key Fields:
  • Codigo - Unique state code (e.g., PENDIENTE_APROBACION)
  • Nombre - Display name
  • Color - UI color representation
  • EsEstadoFinal - Whether this is a terminal state
  • Orden - Display order in workflow
Catalog of possible mission states (DevSolicitudTransporte:18)Key Fields:
  • Codigo - Unique state code (e.g., PROGRAMADA, EN_EJECUCION)
  • Nombre - Display name
  • Descripcion - State description

​
Supporting Tables

  • Vehiculo - Vehicle catalog with maintenance tracking (DevSolicitudTransporte:477)
  • Perfil - User profiles linked to Usuario table (DevSolicitudTransporte:208)
  • Departamento - Organizational departments (DevSolicitudTransporte:252)
  • Lugares - Location registry with GPS coordinates (DevSolicitudTransporte:73)

​
Configuration Management

The application uses environment variables for configuration, loaded via config.py: 
class SQLServerConfig:
    ENGINE = os.getenv('SQL_ENGINE', 'mssql')
    HOST = os.getenv('SQL_HOST', 'localhost')
    PORT = int(os.getenv('SQL_PORT', '1433'))
    NAME = os.getenv('SQL_NAME', '')
    USER = os.getenv('SQL_USER', '')
    PASSWORD = os.getenv('SQL_PASSWORD', '')
The config.py module validates critical configuration on import and emits warnings for missing values (config.py:187)

​
Middleware & Error Handling

The application implements several middleware components:

​
CORS Middleware

Configured to allow all origins for development (main.py:57): 
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

​
Global Exception Handlers

1

Validation Errors

Custom handler translates Pydantic validation errors to Spanish (main.py:70)
2

Unhandled Exceptions

Global exception handler catches all unhandled errors (main.py:127)
3

Response Standardization

All responses follow a consistent format via response_handler.py

​
Folder Structure

source/
├── main.py                 # Application entry point
├── config.py               # Configuration management
├── requirements.txt        # Python dependencies
├── routers/               # HTTP endpoint definitions
│   ├── solicitud_router.py
│   ├── mision_router.py
│   ├── vehiculo_router.py
│   └── ...
├── services/              # Business logic layer
│   ├── base_service.py
│   ├── solicitud_service.py
│   ├── mision_service.py
│   └── ...
├── models/                # Pydantic schemas
│   ├── estado_solicitud_model.py
│   ├── estado_mision_model.py
│   └── ...
├── database/              # Database abstraction
│   ├── sql_connection.py  # SQL Server manager
│   └── mongo_client.py    # MongoDB client
├── utils/                 # Utility modules
│   ├── response_handler.py
│   ├── logging_config.py
│   └── validaciones.py
└── templates/             # Email templates
    └── email/

​
Design Patterns

Singleton Pattern

Database managers use singleton pattern to reuse connections (sql_connection.py:501)

Repository Pattern

Service layer abstracts data access from business logic

Dependency Injection

Configuration injected via get_settings() function (config.py:197)

Context Manager

Database connections managed with Python context managers (sql_connection.py:68)
The architecture supports horizontal scaling by using connection pooling and stateless service design.

​
Next Steps

Workflow States

Learn about request and mission state transitions

Error Handling

Understand error responses and validation

Build docs developers (and LLMs) love

Get started for freeTalk to us