Quickstart

Get B-Accesible running locally in minutes — backend microservices, AI service, and frontend.

Prerequisites

Before you start, make sure you have the following installed:

Docker & Docker Compose

Required to run all backend microservices and the SQL Server database.

Node.js 18+

Required to run the React frontend.

Python 3.9+

Required to run the AI service locally.

Git

Required to clone the repository.

Setup

1. Clone the repository

   git clone https://github.com/Alejandrin08/Hackathon-SPEI.git
   cd Hackathon-SPEI
   
2. Create the backend environment file

   The backend services are configured via a .env file in the backend/ directory. Create it before starting Docker Compose.

   touch backend/.env
   

   Then add the following variables:

   backend/.env

   # Secret key used to sign and verify JWT tokens.
   # Use a long, random string — for example: openssl rand -hex 32
   JWT_SECRET_KEY=your-secure-random-string
   
   # Password for the SQL Server SA account.
   # Must be at least 8 characters and include uppercase, lowercase,
   # a digit, and a special character (SQL Server requirement).
   DB_PASSWORD=YourStr0ng!Password
   

   DB_PASSWORD must meet SQL Server’s password complexity policy: at least 8 characters with uppercase, lowercase, a digit, and a special character. Weak passwords will prevent the database container from starting.

   Generate a secure JWT_SECRET_KEY with openssl rand -hex 32.

3. Start all backend services

   From the backend/ directory, build and start every service with a single command:

   cd backend
   docker compose up --build
   

   Docker Compose will start the following services:

   Service	Port	Description
   ocelot-gateway	5000	API Gateway — all client traffic enters here
   authprofileservice	—	Auth & Profile microservice
   ledgerservice	—	Ledger microservice
   openfinanceservice	—	Open Finance microservice
   analyticsservice	7002	Analytics microservice
   sql-server-db	1433	SQL Server 2022 database

   The first build downloads .NET SDK images and restores NuGet packages, which can take several minutes. Subsequent starts are faster.

4. Start the AI service

   The AI service is a Python FastAPI application that runs separately from Docker Compose. Open a new terminal and run:

   cd backend/ai_service
   pip install -r requirements.txt
   uvicorn serviceapi:app --reload --port 8001
   

   The AI service will be available at http://localhost:8001. It exposes three endpoints: /ai/nudge, /ai/accessibility, and /ai/risk.

   Use a Python virtual environment to keep dependencies isolated:

   python -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   
5. Start the frontend

   Open another terminal and run:

   cd frontend
   npm install
   npm run dev
   

   The frontend is available at http://localhost:5173.

First use walkthrough

Once all services are running, follow these steps to explore the core features:

1. Register an account

   Open http://localhost:5173 and click Sign up. Fill in your name, email, and a password to create your account. The frontend calls POST /api/auth/register through the Ocelot gateway.

2. Complete the accessibility wizard

   After registration, B-Accesible launches the accessibility wizard. The wizard collects behavioral signals and calls /ai/accessibility to recommend a personalized accessibility profile — adjusting font size, contrast, and interaction modes. Complete the wizard to apply your profile.

3. Make a transfer

   Navigate to Transfer from the home screen. Enter a beneficiary and amount. Before you confirm, the app calls /ai/risk to evaluate the transaction. A risk badge is displayed on the confirmation screen. Confirm the transfer to submit it through the Ledger service.

Verify the stack is healthy

You can check that each service is reachable using the gateway:

Check auth service

curl http://localhost:5000/api/auth/health

The AI service ships with a Swagger UI at http://localhost:8001/docs where you can explore and test all three ML endpoints interactively.

Next steps

Architecture overview

Learn how the microservices, gateway, and AI layer fit together.

Accessibility features

Explore the accessibility profile system and wizard in depth.

AI nudging

Understand how behavioral signals drive real-time accessibility adjustments.

API reference

Browse all available API endpoints.