API Gateway for BPOE app

This repository contains a gateway application used to orchestrate communication in Be Part Of the Event application.

Tech Stack

• FastAPI gateway with Starlette middleware (sessions, CORS) and Auth0 authentication helpers.
• Python 3.12 managed via Poetry (production + dev dependency groups).
• Sentry SDK for error monitoring, tracing, and profiling.
• Docker Compose setup for local orchestration of dependencies and the API gateway.
• Postman collection (FAstAPI with Aoth0.postman_collection.json) and static frontend (index.html) for manual auth flows. The HTML file is a developer helper only; production SPA/clients should replicate the PKCE/state flow on their side instead of referencing this file directly.

Overview

The purpose of this project is to build frame for the microservices.

Features

• 2 kinds of frontends communication (web, mobile),
• Auth0 authorisation,
• gateway for:
  • OCR,
  • events service,
  • receipt service,
  • statement/reports service.

Requirements

• Python >=3.12.7 with poetry package manager
• Docker Desktop / Docker + Compose

Getting Started (Windows)

Tip: before running any command copy docker/.env.template to docker/.env (and to the project root if you alter config.search_path). Fill in the Auth0 credentials, session secret, CORS allow-list, and optional Sentry values directly in that file—the inline comments explain every variable.

Deploy

1. Clone the repository:

   git clone https://github.com/Cybernetic-Ransomware/bpoe-api-gateway.git

2. Configure environment variables: cp docker/.env.template docker/.env and update the values.
3. Run using Docker:

   docker-compose -f ./docker/docker-compose.yml up --build

Dev-instance

1. Clone the repository:

   git clone https://github.com/Cybernetic-Ransomware/bpoe-api-gateway.git

2. Configure environment variables: cp docker/.env.template docker/.env and update the values (they are required even for local dev).
3. Install poetry:

   pip install poetry

4. Install dependencies:

   poetry install --with dev

5. Install pre-commit hooks:

   poetry run pre-commit install
   poetry run pre-commit autoupdate
   poetry run pre-commit run --all-files

6. Run the application locally:

   poetry run uvicorn src.main:app --host 0.0.0.0 --port 8080 --reload

Versioning & Releases

1. Daily Commits: Stage your changes and create commits through Commitizen to keep messages consistent:

   git add .
   poetry run cz commit

Testing

Postman

• The repository includes a Postman collection with ready-to-import webhook mockers located under tests/resources/FAstAPI with Aoth0.postman_collection.json.

Pytest

poetry install --with dev
poetry run pytest

• Tests automatically load configuration from tests/.env.test (see tests/conftest.py). Adjust this file to point at staging tenants or fake credentials when needed.

Ruff

poetry install --with dev
poetry run ruff check

Mypy

poetry install --with dev
poetry run mypy .\src\

Codespell

poetry install --with dev
poetry run codespell

Simple Frontend:

python -m http.server 8070

Developer Docs

• The project ships with a MkDocs Material site under doc/ that renders API reference straight from the Python docstrings via mkdocstrings.
• Edit navigation/content in mkdocs.yml and the doc/ directory; auto-generated reference pages live in doc/api/.
• The mkdocs.yml config embeds Mermaid fences via !!python/name tags; because check-yaml cannot parse those safely, this file is excluded from the pre-commit hook (see .pre-commit-config.yaml comment for details).
• Serve docs locally while coding:

  poetry run mkdocs serve

• Produce a static site (generated into site/) ready for hosting:

  poetry run mkdocs build

Observability (Sentry)

• The gateway is instrumented with sentry_sdk inside src/main.py. Set SENTRY_DSN (and the sampling rates) in your environment before starting the service so every exception, trace, and profile is captured in the proper project.
• Telemetry is activated only when SENTRY_DSN is provided; when left blank no events are sent, which is useful for local development.
• send_default_pii is disabled by default to avoid leaking user metadata. Enable it only if your compliance requirements allow attaching identities to errors.
• For local development you can either omit SENTRY_DSN or guard the initialization call to avoid noisy events. For CI/staging, consider reducing traces_sample_rate/profiles_sample_rate to avoid unnecessary volume.
• Consult the official Sentry FastAPI documentation for advanced configuration such as custom scrubbers or sampling rules.

Useful links and documentation

• API Gateway microservice: GitHub
• Databases handler microservice: GitHub
• OCR microservice: GitHub
• Reports microservice: GitHub