System Architecture

Comprehensive overview of Viax’s technical architecture, technology stack, and system design

System Architecture

Viax is built with a modular monolith architecture that follows Clean Architecture principles, preparing the platform for future scalability and potential migration to microservices.

Architecture Overview

Technology Stack

Frontend Technology

Flutter Framework

Flutter SDK 3.35.3+

• Cross-platform development (iOS & Android)
• Hot reload for rapid development
• Native performance with compiled code
• Rich widget library
• Material Design 3 implementation

Key Dependencies:

provider: ^6.1.3              # State management
flutter_map: ^8.2.2           # Interactive maps
geolocator: ^14.0.2           # GPS location
geocoding: ^4.0.0             # Address conversion
http: ^1.1.0                  # HTTP client
shared_preferences: ^2.2.2    # Local storage

State Management

Provider Pattern

• Simple and intuitive
• Built-in to Flutter
• Minimal boilerplate
• Testable architecture

Key Providers:

• AuthProvider - Authentication state
• UserProvider - User profile data
• ConductorProfileProvider - Driver information
• TripProvider - Trip management
• MapProvider - Location and routing

UI/UX

Design System:

• Material Design 3
• Custom color scheme (Blue #2196F3)
• Consistent spacing and typography
• Responsive layouts
• Accessibility support

Components:

• Reusable widgets
• Custom animations
• Shimmer loading effects
• Bottom sheets and dialogs
• Professional onboarding

Backend Technology

Server Stack

// PHP 8.3+ with modern features
- PHP 8.3+
- Apache/Nginx web server
- Composer dependency management
- PSR-4 autoloading
- RESTful API design

External Services

Mapbox

Maps & Routing

• Map tiles: 100,000/month free
• Directions API: 100,000/month free
• Geocoding API
• Static maps

TomTom

Traffic Data

• Real-time traffic: 2,500/day free
• Route optimization
• ETA calculation
• Traffic flow data

Nominatim

Geocoding

• Address to coordinates
• Reverse geocoding
• Unlimited free tier
• OpenStreetMap data

Gmail SMTP

Email Service

• Email verification
• Password reset
• Notifications
• PHPMailer integration

System Components

Mobile Application (Flutter)

Directory Structure:

lib/
├── src/
│   ├── core/                    # Shared functionality
│   │   ├── config/              # App configuration
│   │   ├── di/                  # Dependency injection
│   │   ├── error/               # Error handling
│   │   └── network/             # Network utilities
│   │
│   ├── features/                # Feature modules
│   │   ├── auth/                # Authentication
│   │   ├── user/                # User features
│   │   ├── conductor/           # Driver features
│   │   ├── admin/               # Admin panel
│   │   ├── company/             # Company management
│   │   ├── maps/                # Map integration
│   │   └── trips/               # Trip management
│   │
│   └── routes/                  # Navigation
└── main.dart

Key Modules:

Authentication Module

Capabilities:

• User registration with validation
• Email verification (6-digit codes)
• Secure login/logout
• Password reset flow
• Session management

Security:

• Passwords hashed with bcrypt
• Email verification required
• Input sanitization
• Secure token storage

Map Integration Module

Features:

• Real-time GPS tracking
• Interactive map display
• Marker placement
• Route visualization
• Geocoding/reverse geocoding

Technologies:

• flutter_map for rendering
• geolocator for GPS
• Mapbox API for tiles
• Nominatim for geocoding

Trip Management Module

User Flow:

1. Select pickup location
2. Choose destination
3. Select vehicle type
4. View price estimate
5. Confirm booking
6. Track driver
7. Complete trip

States:

• Pending (searching driver)
• Accepted (driver assigned)
• In Progress (trip ongoing)
• Completed (finished)
• Cancelled (user/driver cancelled)

Driver Module

Registration:

• Personal information form
• Document upload (license, vehicle)
• Background verification
• Admin approval workflow

Operations:

• Toggle availability
• View nearby requests
• Accept/decline trips
• Navigate to pickup
• Update location
• Complete trips

Backend API (PHP)

Service Organization:

backend/
├── auth/                      # Authentication service
│   ├── login.php              # User login
│   ├── register.php           # User registration
│   ├── verify_email.php       # Email verification
│   └── email_service.php      # Email sending
│
├── conductor/                 # Driver service
│   ├── get_profile.php        # Get driver profile
│   ├── update_location.php    # Update GPS location
│   ├── get_pending_requests.php  # View trip requests
│   └── accept_trip_request.php   # Accept trip
│
├── user/                      # User service
│   ├── create_trip_request.php   # Request trip
│   ├── find_nearby_drivers.php   # Find drivers
│   └── get_trip_history.php      # Trip history
│
├── admin/                     # Admin service
│   ├── dashboard_stats.php    # Dashboard metrics
│   ├── user_management.php    # Manage users
│   └── document_verification.php # Verify documents
│
├── config/                    # Configuration
│   ├── database.php           # DB connection
│   └── config.php             # App config
│
└── vendor/                    # Composer dependencies

API Design Principles:

1. RESTful Endpoints

   Standard HTTP methods (GET, POST, PUT, DELETE) with resource-based URLs

2. JSON Responses

   Consistent JSON format with success/error indicators and data payload

3. Error Handling

   Structured error responses with codes, messages, and debugging info

4. Security

   Input validation, SQL injection prevention, and authentication checks

Example API Response:

{
  "success": true,
  "message": "Trip request created successfully",
  "data": {
    "solicitud_id": 123,
    "estado": "pendiente",
    "precio_estimado": 12500,
    "conductores_disponibles": [
      {
        "conductor_id": 42,
        "nombre": "Carlos Rodriguez",
        "distancia_km": 2.3,
        "calificacion": 4.8,
        "tipo_vehiculo": "carro"
      }
    ]
  }
}

Database Schema

Core Entities:

Users

CREATE TABLE usuarios (
  id INT PRIMARY KEY AUTO_INCREMENT,
  nombre_completo VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  telefono VARCHAR(20),
  password_hash VARCHAR(255) NOT NULL,
  email_verificado TINYINT DEFAULT 0,
  codigo_verificacion VARCHAR(6),
  fecha_registro TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  estado ENUM('activo', 'suspendido') DEFAULT 'activo'
);

Drivers

CREATE TABLE conductores (
  id INT PRIMARY KEY AUTO_INCREMENT,
  usuario_id INT NOT NULL,
  nombre_completo VARCHAR(255) NOT NULL,
  telefono VARCHAR(20) NOT NULL,
  direccion TEXT,
  tipo_vehiculo ENUM('moto', 'carro', 'moto_carga', 'carro_carga'),
  latitud_actual DECIMAL(10, 8),
  longitud_actual DECIMAL(11, 8),
  disponibilidad TINYINT DEFAULT 0,
  estado_verificacion ENUM('pendiente', 'aprobado', 'rechazado'),
  calificacion_promedio DECIMAL(3, 2) DEFAULT 0.00,
  FOREIGN KEY (usuario_id) REFERENCES usuarios(id)
);

Trips

CREATE TABLE solicitudes_servicio (
  id INT PRIMARY KEY AUTO_INCREMENT,
  usuario_id INT NOT NULL,
  latitud_origen DECIMAL(10, 8) NOT NULL,
  longitud_origen DECIMAL(11, 8) NOT NULL,
  direccion_origen TEXT,
  latitud_destino DECIMAL(10, 8) NOT NULL,
  longitud_destino DECIMAL(11, 8) NOT NULL,
  direccion_destino TEXT,
  tipo_servicio ENUM('viaje', 'paquete') NOT NULL,
  tipo_vehiculo ENUM('moto', 'carro', 'moto_carga', 'carro_carga'),
  distancia_km DECIMAL(6, 2),
  duracion_minutos INT,
  precio_estimado DECIMAL(10, 2),
  estado ENUM('pendiente', 'aceptada', 'en_curso', 'completada', 'cancelada'),
  fecha_solicitud TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (usuario_id) REFERENCES usuarios(id)
);

Documents

CREATE TABLE documentos_conductor (
  id INT PRIMARY KEY AUTO_INCREMENT,
  conductor_id INT NOT NULL,
  tipo_documento ENUM('licencia_conduccion', 'cedula', 'seguro_vehiculo', 'tarjeta_propiedad'),
  numero_documento VARCHAR(100),
  fecha_expedicion DATE,
  fecha_vencimiento DATE,
  ruta_archivo VARCHAR(500),
  estado_verificacion ENUM('pendiente', 'aprobado', 'rechazado'),
  observaciones TEXT,
  FOREIGN KEY (conductor_id) REFERENCES conductores(id)
);

Relationships:

Deployment Architecture

Production Environment

Current production setup on VPS infrastructure

VPS Server (76.13.114.194)
├── Apache Web Server
│   ├── Virtual Host: /var/www/viax/backend
│   └── PHP 8.3 Module
│
├── MySQL Server
│   ├── Database: viax_production
│   └── User: viax_user
│
├── File Storage
│   ├── uploads/documents/
│   └── logs/
│
└── SSL/TLS (Future)
    └── Let's Encrypt Certificate

Deployment Flow:

1. Code Preparation

   git pull origin main
   composer install --no-dev --optimize-autoloader
   
2. Database Migration

   php migrations/run_migrations.php
   
3. Permissions

   chmod 755 logs uploads
   chown -R www-data:www-data /var/www/viax/backend
   
4. Service Restart

   sudo systemctl restart apache2
   sudo systemctl restart mysql
   
5. Health Check

   curl http://76.13.114.194/health.php
   

Development Environment

Local Setup with Laragon:

C:/laragon/
├── bin/
│   ├── apache/
│   ├── mysql/
│   └── php/
│
├── www/
│   └── viax/
│       └── backend/    # Backend code here
│
└── data/
    └── mysql/         # Database files

Performance Considerations

Optimization Strategies

Database Indexing

• Primary keys on all tables
• Indexes on foreign keys
• Composite indexes for queries
• Geospatial indexes for location

Caching

• Shared preferences for user data
• In-memory driver location cache
• API response caching
• Static asset caching

Query Optimization

• Prepared statements
• Join optimization
• Limit result sets
• Pagination for large datasets

Asset Optimization

• Compressed images
• Lazy loading
• CDN for static files (future)
• Minified JSON responses

Scalability Path

Current Capacity:

• ~1,000 concurrent users
• ~200 active drivers
• ~500 trips per day

Scaling Options:

1. Vertical Scaling (Short-term)

   • Upgrade VPS resources
   • Increase database memory
   • Optimize queries

2. Horizontal Scaling (Medium-term)

   • Load balancer
   • Multiple app servers
   • Database replication
   • Redis for caching

3. Microservices (Long-term)

   • Separate services
   • Container orchestration
   • Message queues
   • Service mesh

Security Architecture

Security measures implemented to protect user data and system integrity

Security Layers

Application Security
├── Input Validation
├── SQL Injection Prevention (Prepared Statements)
├── XSS Protection
└── CSRF Tokens (Future)

Authentication & Authorization
├── Password Hashing (bcrypt)
├── Email Verification
├── Session Management
└── Role-Based Access Control

Data Security
├── HTTPS/TLS (Future)
├── Database Encryption
├── Secure File Storage
└── Audit Logging

Network Security
├── Firewall Rules
├── Rate Limiting (Future)
├── DDoS Protection
└── API Key Management

Viax’s architecture is designed for reliability, performance, and future growth while maintaining clean code principles and security best practices.