Services reference

Detailed reference for every microservice in the B-Accesible backend stack.

B-Accesible is composed of six backend services. Five run as Docker containers managed by Docker Compose. The AI Service runs as a standalone Python process.

Services overview

OcelotGateway

API Gateway. Routes all client requests to downstream services and validates JWT tokens.

AuthService

User registration, login, JWT issuance, accessibility profiles, and GDPR consent.

LedgerService

SPEI-based bank accounts, transactions, and beneficiary management.

OpenFinanceService

Connections to external banks and syncing of external financial products.

AnalyticsService

Receives and stores user interaction events for accessibility impact measurement.

AI Service

Python FastAPI service running nudging, accessibility profiling, and risk scoring models.

---

OcelotGateway

Container: hackathon-gateway
External port: 5000 → internal 8080

The API Gateway is the single entry point for all client requests. It uses the Ocelot library for .NET to route requests to the correct downstream service based on path prefixes defined in ocelot.json. JWT tokens are validated at the gateway before any request is forwarded.

Routing configuration

Routes are defined in OcelotGateway/ocelot.json. Each route entry maps an upstream path template to a downstream service host and port.

ocelot.json (excerpt)

{
  "Routes": [
    {
      "UpstreamPathTemplate": "/api/auth/{everything}",
      "UpstreamHttpMethod": [ "GET", "POST", "PUT", "DELETE" ],
      "DownstreamPathTemplate": "/api/auth/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        { "Host": "authprofileservice", "Port": 8080 }
      ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "http://localhost:5000"
  }
}

JWT validation

The gateway validates Bearer tokens on all protected routes. Tokens must be signed with JWT_SECRET_KEY, have issuer https://api.backendAuth.com, and audience https://app.backendAuth.com.

Public routes (registration, login) pass through without validation.

Running the gateway

The gateway starts automatically with Docker Compose. To rebuild and restart only the gateway:

docker compose up --build -d ocelot-gateway

---

AuthService

Container: hackathon-auth
Database: auth_db

Handles all identity and profile operations: user registration, login, JWT token issuance, accessibility profile management, and GDPR consent recording.

Controllers

Controller	Base path	Responsibilities
AuthController	/api/auth	Register, login, token refresh
ProfileController	/api/profile	Read and update user profile, accessibility settings, GDPR consent

Key endpoints

Method	Path	Auth required	Description
POST	/api/auth/register	No	Create a new user account
POST	/api/auth/login	No	Authenticate and receive a JWT
GET	/api/profile	Yes	Retrieve the authenticated user’s profile
PUT	/api/profile/accessibility	Yes	Update accessibility preferences

Running AuthService

Via Docker Compose

docker compose up --build -d authprofileservice

---

LedgerService

Container: hackathon-ledger
Database: ledger_db

Manages SPEI-compatible bank accounts, processes transactions between accounts, and handles beneficiary lists. All endpoints require a valid JWT.

Controller

Controller	Base path	Responsibilities
LedgerController	/api/ledger	Account management, SPEI transfers, beneficiary CRUD

Key endpoints

Method	Path	Description
GET	/api/ledger/account	Get the authenticated user’s account and balance
POST	/api/ledger/transfer	Initiate a SPEI transfer
GET	/api/ledger/transactions	List transaction history
POST	/api/ledger/beneficiaries	Add a beneficiary
GET	/api/ledger/beneficiaries	List beneficiaries

Running LedgerService

Via Docker Compose

docker compose up --build -d ledgerservice

---

OpenFinanceService

Container: hackathon-openfinance
Database: openfinance_db

Allows users to link external bank accounts and syncs their external financial products into the B-Accesible platform. All endpoints require a valid JWT.

Controller

Controller	Base path	Responsibilities
OpenFinanceController	/api/openfinance	Manage external bank connections and sync financial products

Key endpoints

Method	Path	Description
POST	/api/openfinance/connect	Link an external bank account
GET	/api/openfinance/connections	List active external connections
POST	/api/openfinance/sync	Sync financial products from connected banks

Running OpenFinanceService

Via Docker Compose

docker compose up --build -d openfinanceservice

---

AnalyticsService

Container: hackathon-analytics
External port: 7002 → internal 8080
Database: analytics_db

Receives user interaction events from the frontend and stores them for analysis. Used to measure how accessibility features affect user behaviour and task completion rates.

Controller

Controller	Base path	Responsibilities
AnalyticsController	/api/analytics	Ingest interaction events, query aggregated metrics

Why it has a direct port

The Analytics Service is exposed on port 7002 in addition to being reachable through the gateway. This allows the frontend to fire-and-forget event payloads directly without adding latency to the gateway pipeline.

Running AnalyticsService

Via Docker Compose

docker compose up --build -d analyticsservice

---

AI Service

Port: 8001
Runtime: Python 3.11+ / FastAPI / uvicorn
Not included in Docker Compose — run separately

A standalone Python service that exposes three machine-learning endpoints. Models are scikit-learn Decision Trees trained on synthetic data and serialized as .pkl files.

Routes

Method	Path	Model	Description
POST	/ai/nudge	nudging_model.pkl	Recommends financial nudges based on user behaviour
POST	/ai/accessibility	accessibility_model.pkl	Infers an accessibility profile from interaction patterns
POST	/ai/risk	risk_model.pkl	Scores transaction risk
GET	/ai/health	—	Liveness check — returns 200 OK when all models are loaded

Model files

Model files must be present before starting the service:

backend/ai_service/models/
├── nudging_model.pkl
├── accessibility_model.pkl
└── risk_model.pkl

If any model file is missing, the service will raise an error on startup.

Starting the AI Service

Start with uvicorn

cd backend/ai_service
uvicorn serviceapi:app --host 0.0.0.0 --port 8001 --reload

Use --reload during development so the server restarts automatically when you edit serviceapi.py.

CORS is configured to allow requests from http://localhost:5173 (the Vite dev server) only.

Health check

curl http://localhost:8001/ai/health

Expected response when all three models are loaded:

{ "status": "ok", "models_loaded": 3 }

---

SQL Server 2022

Container: hackathon-sql-server
Port: 1433
Volume: sql-server-data (persistent across restarts)

A single SQL Server 2022 instance hosts four separate databases, one per service.

Database	Owner service
auth_db	AuthService
ledger_db	LedgerService
openfinance_db	OpenFinanceService
analytics_db	AnalyticsService

Connecting with a SQL client

You can connect to SQL Server directly for inspection or debugging:

Setting	Value
Host	localhost
Port	1433
Username	sa
Password	123SPEI (default in docker-compose.yml)
Authentication	SQL Server Authentication

Persisting data

Data is stored in the sql-server-data Docker volume and survives container restarts. To completely reset all databases, remove the volume:

docker compose down -v

This permanently deletes all data in all four databases.