DivTrade

Completely functional MVP: https://div-trade-mvp.vercel.app/

Whole web app with future improvements https://div-trade.vercel.app/

Project description and objectives

DivTrade is a two-part application consisting of a FastAPI backend (DivTrade_Backend) and a Vite + React frontend (DivTrade_Frontend).

The backend scrapes currency listings from Revolico, applies data-cleaning rules, and exposes HTTP endpoints consumed by the frontend. The frontend visualizes current rates, historical trends, sources, and community feedback.

Objectives:

• Provide near real-time reference rates for informal FX markets in Cuba.
• Normalize noisy listings with rules such as currency exclusions (e.g., CAD) and outlier removal (+/-150 CUP from median).
• Offer a simple, documented API and a modern UI for users to consult current and historical prices.

Team members

CodeBreakers

• Alvaro Vladimir Besada Ferrer
• Guillermo Hughes Cardona

Repository structure

• DivTrade_Backend/
  • api/
    • index.py (FastAPI app setup + CORS + routes)
    • routes_backend.py (HTTP endpoints)
    • scraper.py (Revolico scraping + data processing)
    • redis_client.py (Upstash REST helpers)
    • init.py (package marker)
  • requirements.txt
  • vercel.json (optional deployment config)
  • .env.local (local environment variables; do not commit secrets)
• DivTrade_Frontend/
  • package.json
  • vite.config.ts
  • src/ ... (React components)
  • .env.production

Prerequisites

• Python 3.10+
• Node.js 18+

Setup and usage instructions

Backend: environment variables

Backend uses the following variables (typically via .env.local in DivTrade_Backend/) for an online Upstash DB:

KV_REST_API_URL="https://allowed-cardinal-44603.upstash.io" KV_REST_API_TOKEN="Aa47AAIncDI3ZWY4YTQ0NTEzZjM0YzdlOGM1YmYwZDUxMzRkNDAxZnAyNDQ2MDM"

(Of course, these are the credentials for a testing database, so nothing breaks in production)

Backend: run locally

1. Create and activate a virtual environment (recommended)

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies

pip install -r DivTrade_Backend/requirements.txt

3. Start the API server

uvicorn DivTrade_Backend.api.index:app --host 0.0.0.0 --port 8000

4. Test endpoints

• Health: http://localhost:8000/api/health
• Rates: http://localhost:8000/api/rates
• Cron scrape (updates cache): http://localhost:8000/api/cron/scrape

Notes

• The backend loads environment variables from DivTrade_Backend/.env.local.
• Cached results are stored in Upstash if variables are present; otherwise caching is skipped.
• The backend filters out Canadian dollar ads (CAD), removes outliers > +/-150 CUP from the median, and returns the latest 50 ads by updatedAt.

Frontend: run locally

1. Install dependencies

cd DivTrade_Frontend
npm install

2. Start the dev server

npm run dev

By default Vite will run at http://localhost:5173

If you need to point the frontend to a different backend URL, configure it in DivTrade_Frontend/src/lib/api.ts or via an environment variable depending on your implementation.

Extra relevant information

• Branch strategy: each repository maintains a dedicated mvp branch for the Minimum Viable Product and a main branch for the complete project.
• Ensure DivTrade_Backend/api/init.py exists so the api/ folder is a Python package and relative imports work.
• Run the backend from the repository root using the dotted module path (as shown in the uvicorn command) so imports resolve properly.
• If Revolico changes its HTML structure, you may need to update scraper.py (NEXT_DATA_REGEX or normalization logic).
• For production (Vercel or others), set env vars in the platform and ensure CORS origins in DivTrade_Backend/api/index.py include your deployed frontend URL(s).

API summary (backend)

• GET /api/health — status and cache state
• GET /api/rates — latest processed Revolico snapshot; uses Upstash cache when present
• GET /api/cron/scrape — triggers scraping and updates the cache (30 min TTL)

License

See LICENSE files in the respective folders.