Architecture Overview

System Overview

Mi API BCV is built on Laravel 12 and follows a layered architecture that separates concerns between data collection, storage, and API delivery. The system uses the Strategy pattern for extensibility and Laravel’s built-in features for caching, scheduling, and database management.

High-Level Architecture

┌─────────────────┐
│   HTTP Client   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  API Routes     │  (routes/api.php)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Controller     │  (ScraperController)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Cache Layer    │  (1-hour TTL)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Eloquent ORM   │  (ReferenceRecord)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Database     │  (SQLite/MySQL/PostgreSQL)
└─────────────────┘

Data Update Flow

┌─────────────────┐
│  Cron Scheduler │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ rates:update    │  (FetchExchangeRates command)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ UrlProvider     │  (Strategy context)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ UrlStrategy     │  (BCV, Banplus, BNC, BDV)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ScraperService  │  (HTTP + DOM parsing)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ReferenceRecord │  (Eloquent model)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ReferenceObserver│ (Cache invalidation)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Database     │
└─────────────────┘

Core Components

API Layer

Location: app/Http/Controllers/Api/ScraperController.php The API controller handles HTTP requests and provides two main endpoints:

GET / - Returns today’s rates from all banks
GET /info/{date}/{source?} - Returns historical rates with optional filtering

Both endpoints implement caching with 1-hour TTL to reduce database load.

public function show(Request $request)
{
    $this->logApi($request);
    
    $cacheKey = 'tasas_bancos_' . now()->toDateString();
    
    $records = Cache::remember($cacheKey, 3600, function () {
        return ReferenceRecord::where('date', now()->toDateString())
            ->get()
            ->keyBy('source');
    });
    
    // ... response formatting
}

Data Collection Layer

ScraperService (app/Services/ScraperService.php) Handles HTTP requests and HTML parsing for each bank’s website:

Configures HTTP client with browser headers
Uses Symfony DomCrawler for HTML parsing
Applies bank-specific parsing logic
Normalizes decimal values

UrlProviderService (app/Services/UrlProviderService.php) Acts as the Strategy pattern context, managing concrete URL strategies for each bank.

Strategy Pattern Implementation

UrlStrategy Interface (app/Interfaces/UrlStrategy.php)

interface UrlStrategy
{
    public function getValue(): float;
}

Concrete Strategies:

UrlBcv - Scrapes Banco Central de Venezuela
UrlBanplus - Scrapes Banplus news ticker
UrlBnc - Scrapes Banco Nacional de Crédito
UrlBdv - Fetches from Banco de Venezuela (JSON API)

Each strategy:

Defines the target URL
Calls ScraperService with bank identifier
Returns the parsed exchange rate value

Data Model

ReferenceRecord (app/Models/ReferenceRecord.php) Eloquent model representing exchange rate records:

Schema::create('reference_records', function (Blueprint $table) {
    $table->id();
    $table->string('source');        // Bank identifier
    $table->decimal('value', 64, 4); // Exchange rate
    $table->date('date');            // Rate date
    $table->timestamps();
});

ReferenceObserver (app/Observers/ReferenceObserver.php) Automatically invalidates cache when records are created or updated, ensuring API responses stay fresh.

Scheduled Tasks

FetchExchangeRates Command (app/Console/Commands/FetchExchangeRates.php)

protected $signature = 'rates:update';
protected $description = 'Consulta el BCV y otros bancos para actualizar tasas';

Iterates through all configured banks and:

Checks if today’s rate already exists
Fetches new rate via appropriate strategy
Saves to database
Logs success/failure
Continues with next bank if one fails

Design Patterns

Strategy Pattern

Purpose: Allow easy addition of new bank sources without modifying existing code Benefits:

Open/Closed Principle: Open for extension, closed for modification
Each bank’s scraping logic is isolated
Easy to test individual strategies
Simple to add new banks

Observer Pattern

Purpose: Automatically invalidate cache when data changes Implementation: ReferenceObserver listens to Eloquent model events Benefits:

Decouples cache management from business logic
Ensures data consistency
Centralized cache invalidation logic

Repository Pattern (via Eloquent)

Purpose: Abstract database operations Implementation: Laravel’s Eloquent ORM Benefits:

Database-agnostic code
Query builder and relationships
Migration support

Laravel Components Used

HTTP Client

Http::withoutVerifying()->withHeaders([
    'User-Agent' => 'Mozilla/5.0 ...',
    'Accept' => 'text/html,application/xhtml+xml',
])->get($url);

Configured to bypass SSL verification and mimic browser requests.

Cache Facade

Cache::remember($key, $ttl, $callback);

Supports multiple drivers: database, file, Redis, Memcached.

Console Commands

Artisan commands for manual and scheduled rate updates.

Task Scheduling

Laravel’s scheduler (configured via cron) runs rates:update daily.

Directory Structure

app/
├── Console/
│   └── Commands/
│       └── FetchExchangeRates.php  # Scheduler command
├── Http/
│   └── Controllers/
│       └── Api/
│           └── ScraperController.php  # API endpoints
├── Interfaces/
│   └── UrlStrategy.php              # Strategy interface
├── Models/
│   └── ReferenceRecord.php          # Eloquent model
├── Observers/
│   └── ReferenceObserver.php        # Cache invalidation
├── Services/
│   ├── ScraperService.php           # Web scraping
│   └── UrlProviderService.php       # Strategy provider
└── Strategies/
    └── Url/
        ├── UrlBcv.php               # BCV strategy
        ├── UrlBanplus.php           # Banplus strategy
        ├── UrlBnc.php               # BNC strategy
        └── UrlBdv.php               # BDV strategy

routes/
└── api.php                          # API route definitions

database/
└── migrations/
    └── 2026_01_28_203351_create_reference_records_table.php

Data Flow Examples

API Request Flow

Client sends GET / request
Route dispatches to ScraperController::show()
Controller checks cache for today’s rates
If cache miss, query database
Format response as JSON
Cache result for 1 hour
Return to client

Scheduled Update Flow

Cron triggers php artisan rates:update
Command iterates: ['bdv', 'banplus', 'bnc', 'bcv']
For each bank:
- Check if today’s record exists (skip if yes)
- Call UrlProviderService::getStrategy($bank)
- Strategy calls ScraperService::scrapeData($url, $bank)
- ScraperService fetches HTML and parses
- Strategy returns float value
- Command saves to ReferenceRecord
- Observer invalidates cache
Log completion

Performance Optimizations

Caching Strategy

TTL: 1 hour (rates don’t change frequently)
Key Format: tasas_bancos_YYYY-MM-DD
Invalidation: Automatic via Observer
Driver: Configurable (file, database, Redis)

Database Indexing

Recommended indexes:

CREATE INDEX idx_source_date ON reference_records(source, date);
CREATE INDEX idx_date ON reference_records(date);

HTTP Optimization

Reuse HTTP client connections
Set reasonable timeouts
Handle failures gracefully

Error Handling

API Layer

404 when no rates available
400 for invalid date formats
404 for unknown routes (fallback handler)

Scraper Layer

Try/catch around each bank fetch
Log errors but continue with next bank
Throw exceptions for missing DOM elements

Command Layer

Per-bank error isolation
Comprehensive logging
Graceful degradation

Security Considerations

Input Validation

private function validateDate(&$date)
{
    $dt = Carbon::parse($date);
    return $dt->lessThanOrEqualTo(now());
}

Rate Limiting

No built-in rate limiting (consider adding Laravel’s throttle middleware for production).

CORS

Configure in config/cors.php for production deployments.

Next Steps

ScraperService Deep Dive

Learn how web scraping works in detail

Strategy Pattern

Understand the Strategy pattern implementation

Adding Banks

Extend the system with new data sources

Scheduler Setup

Configure automatic rate updates

Architecture

Extending

Documentation Index

​System Overview

​High-Level Architecture

​Data Update Flow

​Core Components

​API Layer

​Data Collection Layer

​Strategy Pattern Implementation

​Data Model

​Scheduled Tasks

​Design Patterns

​Strategy Pattern

​Observer Pattern

​Repository Pattern (via Eloquent)

​Laravel Components Used

​HTTP Client

​Cache Facade

​Console Commands

​Task Scheduling

​Directory Structure

​Data Flow Examples

​API Request Flow

​Scheduled Update Flow

​Performance Optimizations

​Caching Strategy

​Database Indexing

​HTTP Optimization

​Error Handling

​API Layer

​Scraper Layer

​Command Layer

​Security Considerations

​Input Validation

​Rate Limiting

​CORS

​Next Steps

ScraperService Deep Dive

Strategy Pattern

Adding Banks

Scheduler Setup

Build docs developers (and LLMs) love

System Overview

High-Level Architecture

Data Update Flow

Core Components

API Layer

Data Collection Layer

Strategy Pattern Implementation

Data Model

Scheduled Tasks

Design Patterns

Strategy Pattern

Observer Pattern

Repository Pattern (via Eloquent)

Laravel Components Used

HTTP Client

Cache Facade

Console Commands

Task Scheduling

Directory Structure

Data Flow Examples

API Request Flow

Scheduled Update Flow

Performance Optimizations

Caching Strategy

Database Indexing

HTTP Optimization

Error Handling

API Layer

Scraper Layer

Command Layer

Security Considerations

Input Validation

Rate Limiting

CORS

Next Steps