cilt-uct/brightspace-middleware-lite

1. What this service is for

This repo implements a middleware service between the Tsugi migration tool and D2L Brightspace. Its core job is to wrap Brightspace calls with the correct OAuth 2.0 access token and keep that token refreshed over time.

2. Top-level deployment shape

The app is containerized and split into a reverse proxy layer and a Flask web service layer. app/services/nginx contains nginx config/Dockerfile, while app/services/web contains the Python application served through Gunicorn. docker-compose.yml ties these pieces together.

3. Web application boundary

The Flask service is split into two presentation surfaces:

- project/site/* for server-rendered UI pages such as login, register, logout, and system pages

- project/api/* for the programmatic API used by the migration workflow

Templates and static assets live under project/templates and project/static, so the UI is mostly server-side rendered with some JavaScript helpers.

4. Brightspace integration layer

The project/d2l package is the main adapter to Brightspace. It is subdivided by domain: courses, content, roles, and users, plus shared pieces like client, oauth, response, decorators, and exceptions. This is the boundary where the app translates internal requests into Brightspace API calls.

5. Local persistence and state

The project/db package handles persistence, with modules for the main client, logs, and system data. The repository includes app/database.sql, indicating a local relational schema used to store service state such as tokens, settings, logs, and possibly user/account records.

6. OAuth and token lifecycle

OAuth is treated as a first-class concern. The d2l/oauth.py module likely handles authorization and token exchange, while the scheduler process (project/run_scheduler.py) exists specifically to refresh tokens automatically. This means the service is not just a stateless proxy; it owns credential lifecycle state.

7. API resource model

The API is organized around Brightspace-style resources: users, courses, roles, contents, and settings. That suggests the middleware exposes a domain-oriented interface rather than a generic proxy, mapping migration operations onto Brightspace entities.

8. Background processing

The README explicitly calls out an APScheduler-based component. Architecturally, this is the asynchronous support plane for the service: it runs independently of request/response traffic and keeps authentication material valid in the background.

9. Security and request guards

There are project-level decorators plus D2L-specific decorators, implying access control and token/state validation around both UI and API routes. Forms and system pages suggest there is user-facing authentication/registration in addition to machine-driven API usage.

10. Front-end and client-side assets

The front end is mostly traditional Flask/Jinja with bundled CSS/JS libraries. There is a flask_jsglue integration and a js_bridge.js template, which indicates the server exposes some route/config data to client-side code rather than building a full SPA.

11. Configuration and runtime entrypoints

Runtime configuration is driven by environment files and app-level config modules (project/config.py, project/site/settings.py, project/api/settings.py). The service has explicit entrypoints for Gunicorn and a shell-based startup script, so the app is designed to run as a long-lived containerized web process plus a separate scheduler process.

12. Overall data flow

A typical request path is: UI/API request enters nginx, reaches Flask/Gunicorn, hits a site or API route, which may query local DB state, then calls the D2L client layer to invoke Brightspace with the current OAuth token. Separately, the scheduler refreshes tokens and updates stored state so subsequent migration calls continue to work.