# allardnaber/bsmain architecture

> Architecture diagram of the GitHub repository allardnaber/bsmain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/allardnaber/bsmain
- Repository: https://github.com/allardnaber/bsmain

## Overview

This repository is a PHP client/runtime for building Brightspace integrations: application code handles incoming routes, then uses a configured API client to authenticate and access Brightspace resources. The graph emphasizes that request path, alongside reusable resource APIs, configuration, token persistence, and data-object conversion. README content was not provided, so capability coverage is based on the source tree and SOURCE INDEX; unsampled features are grouped only where their paths are explicit.

Main entry points: [`src/BsMain/Api/BsApiClient.php`](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/BsApiClient.php) (API client), [`src/BsMain/App.php`](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/App.php) (App bootstrap), [`src/BsMain/Api/BsResourceBaseApi.php`](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/BsResourceBaseApi.php) (API transport), [`src/BsMain/Controller/BsBaseController.php`](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/BsBaseController.php) (Controller base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application runtime"]
  node_app_runtime["App bootstrap<br/>[App.php]"]
  node_routes["Route discovery<br/>[RouteFactory.php]"]
  node_controller["Controller base"]
  node_account["Account controller"]
  node_template["Template output<br/>[OutputTemplate.php]"]
  node_session["Session manager<br/>[SessionManager.php]"]
  node_errors["Error handling<br/>[ErrorHelper.php]"]
end

subgraph group_api["Brightspace API"]
  node_client["API client<br/>[BsApiClient.php]"]
  node_transport["API transport"]
  node_resources["Resource APIs"]
  node_uploads["File uploads"]
end

subgraph group_auth["OAuth authentication"]
  node_oauth_base["Token lifecycle"]
  node_service_tokens["Service token selection"]
  node_client_token["Client OAuth"]
  node_db_token["Database token store"]
  node_file_token["File token store"]
end

subgraph group_config["Configuration"]
  node_configuration["Config resolution<br/>[Configuration.php]"]
  node_vault["Vault secrets<br/>[Vault.php]"]
end

subgraph group_models["Data and errors"]
  node_data_objects["Typed API data<br/>[GenericObject.php]"]
  node_api_errors["API exceptions"]
  node_runtime_errors["Runtime exceptions"]
end

node_caller(("Integration caller"))
node_brightspace{{"Brightspace service"}}
node_db[("Token database")]
node_token_file["Persistent token file"]

node_caller -->|"invokes"| node_app_runtime
node_app_runtime -->|"builds routes"| node_routes
node_app_runtime -->|"initializes"| node_controller
node_app_runtime -->|"initializes"| node_template
node_app_runtime -->|"initializes"| node_session
node_app_runtime -->|"uses"| node_errors
node_routes -->|"routes to"| node_controller
node_account -->|"extends"| node_controller
node_account -->|"calls"| node_client
node_controller -->|"renders through"| node_template
node_controller -->|"reads"| node_configuration
node_client -->|"reads"| node_configuration
node_client -->|"selects token handler"| node_oauth_base
node_client -->|"creates lazily"| node_resources
node_client -->|"gets identity"| node_brightspace
node_resources -->|"inherits requests"| node_transport
node_transport -->|"uses credentials"| node_client
node_transport -->|"sends requests"| node_brightspace
node_transport -->|"converts responses"| node_data_objects
node_transport -->|"raises on HTTP error"| node_api_errors
node_transport -->|"raises on transport error"| node_runtime_errors
node_resources -->|"uses uploader"| node_uploads
node_oauth_base -->|"refreshes token"| node_brightspace
node_client -->|"selects service mode"| node_service_tokens
node_service_tokens -->|"selects database"| node_db_token
node_service_tokens -->|"selects file"| node_file_token
node_client -->|"selects user mode"| node_client_token
node_db_token -->|"reads and writes"| node_db
node_file_token -->|"reads and writes"| node_token_file
node_configuration -->|"resolves secrets"| node_vault
node_configuration -->|"raises config errors"| node_runtime_errors
node_oauth_base -->|"reads settings"| node_configuration
node_data_objects -.->|"validates data"| node_runtime_errors

click node_app_runtime "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/App.php"
click node_routes "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/RouteFactory.php"
click node_controller "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/BsBaseController.php"
click node_account "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/AccountController.php"
click node_template "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Template/OutputTemplate.php"
click node_session "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/SessionManager.php"
click node_errors "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/ErrorHelper.php"
click node_client "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/BsApiClient.php"
click node_transport "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/BsResourceBaseApi.php"
click node_resources "https://github.com/allardnaber/bsmain/tree/main/src/BsMain/Api"
click node_uploads "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/Util/ResumableFileUploader.php"
click node_oauth_base "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthTokenHandler.php"
click node_service_tokens "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthServiceTokenHandler.php"
click node_client_token "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthClientTokenHandler.php"
click node_db_token "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthDatabaseServiceTokenHandler.php"
click node_file_token "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthFileServiceTokenHandler.php"
click node_configuration "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Configuration/Configuration.php"
click node_vault "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Configuration/Vault.php"
click node_data_objects "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Data/GenericObject.php"
click node_api_errors "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Exception/BsAppApiException.php"
click node_runtime_errors "https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Exception/BsAppRuntimeException.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_runtime,node_routes,node_controller,node_account,node_template,node_session,node_errors toneBlue
class node_client,node_transport,node_resources,node_uploads,node_db toneAmber
class node_oauth_base,node_service_tokens,node_client_token,node_db_token,node_file_token toneMint
class node_configuration,node_vault toneRose
class node_data_objects,node_api_errors,node_runtime_errors,node_caller,node_brightspace,node_token_file toneIndigo
```

## Components

### Application runtime

- [App bootstrap](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/App.php): `src/BsMain/App.php`
- [Route discovery](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/RouteFactory.php): `src/BsMain/Controller/RouteFactory.php`
- [Controller base](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/BsBaseController.php): `src/BsMain/Controller/BsBaseController.php`
- [Account controller](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/AccountController.php): `src/BsMain/Controller/AccountController.php`
- [Template output](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Template/OutputTemplate.php): `src/BsMain/Template/OutputTemplate.php`
- [Session manager](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/SessionManager.php): `src/BsMain/SessionManager.php`
- [Error handling](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Controller/ErrorHelper.php): `src/BsMain/Controller/ErrorHelper.php`

### Brightspace API

- [API client](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/BsApiClient.php): `src/BsMain/Api/BsApiClient.php`
- [API transport](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/BsResourceBaseApi.php): `src/BsMain/Api/BsResourceBaseApi.php`
- [Resource APIs](https://github.com/allardnaber/bsmain/tree/main/src/BsMain/Api): `src/BsMain/Api`
- [File uploads](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/Util/ResumableFileUploader.php): `src/BsMain/Api/Util/ResumableFileUploader.php`

### OAuth authentication

- [Token lifecycle](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthTokenHandler.php): `src/BsMain/Api/OauthToken/OauthTokenHandler.php`
- [Service token selection](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthServiceTokenHandler.php): `src/BsMain/Api/OauthToken/OauthServiceTokenHandler.php`
- [Client OAuth](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthClientTokenHandler.php): `src/BsMain/Api/OauthToken/OauthClientTokenHandler.php`
- [Database token store](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthDatabaseServiceTokenHandler.php): `src/BsMain/Api/OauthToken/OauthDatabaseServiceTokenHandler.php`
- [File token store](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Api/OauthToken/OauthFileServiceTokenHandler.php): `src/BsMain/Api/OauthToken/OauthFileServiceTokenHandler.php`

### Configuration

- [Config resolution](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Configuration/Configuration.php): `src/BsMain/Configuration/Configuration.php`
- [Vault secrets](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Configuration/Vault.php): `src/BsMain/Configuration/Vault.php`

### Data and errors

- [Typed API data](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Data/GenericObject.php): `src/BsMain/Data/GenericObject.php`
- [API exceptions](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Exception/BsAppApiException.php): `src/BsMain/Exception/BsAppApiException.php`
- [Runtime exceptions](https://github.com/allardnaber/bsmain/blob/main/src/BsMain/Exception/BsAppRuntimeException.php): `src/BsMain/Exception/BsAppRuntimeException.php`

### Other components

- **Integration caller**
- **Brightspace service**
- **Token database**
- **Persistent token file**

## Connections

- Integration caller → App bootstrap: invokes (evidence: `src/BsMain/App.php`)
- App bootstrap → Route discovery: builds routes (evidence: `src/BsMain/App.php`)
- App bootstrap → Controller base: initializes (evidence: `src/BsMain/App.php`)
- App bootstrap → Template output: initializes (evidence: `src/BsMain/App.php`)
- App bootstrap → Session manager: initializes (evidence: `src/BsMain/App.php`)
- App bootstrap → Error handling: uses (evidence: `src/BsMain/App.php`)
- Route discovery → Controller base: routes to (evidence: `src/BsMain/Controller/RouteFactory.php`)
- Account controller → Controller base: extends (evidence: `src/BsMain/Controller/AccountController.php`)
- Account controller → API client: calls (evidence: `src/BsMain/Controller/AccountController.php`)
- Controller base → Template output: renders through (evidence: `src/BsMain/Controller/BsBaseController.php`)
- Controller base → Config resolution: reads (evidence: `src/BsMain/Controller/BsBaseController.php`)
- API client → Config resolution: reads (evidence: `src/BsMain/Api/BsApiClient.php`)
- API client → Token lifecycle: selects token handler (evidence: `src/BsMain/Api/BsApiClient.php`)
- API client → Resource APIs: creates lazily (evidence: `src/BsMain/Api/BsApiClient.php`)
- API client → Brightspace service: gets identity (evidence: `src/BsMain/Api/BsApiClient.php`)
- Resource APIs → API transport: inherits requests (evidence: `src/BsMain/Api/BsEnrollmentsApi.php`)
- API transport → API client: uses credentials (evidence: `src/BsMain/Api/BsResourceBaseApi.php`)
- API transport → Brightspace service: sends requests (evidence: `src/BsMain/Api/BsResourceBaseApi.php`)
- API transport → Typed API data: converts responses (evidence: `src/BsMain/Api/BsResourceBaseApi.php`)
- API transport → API exceptions: raises on HTTP error (evidence: `src/BsMain/Api/BsResourceBaseApi.php`)
- API transport → Runtime exceptions: raises on transport error (evidence: `src/BsMain/Api/BsResourceBaseApi.php`)
- Resource APIs → File uploads: uses uploader (evidence: `src/BsMain/Api/BsAssignmentApi.php`)
- Token lifecycle → Brightspace service: refreshes token (evidence: `src/BsMain/Api/OauthToken/OauthTokenHandler.php`)
- API client → Service token selection: selects service mode (evidence: `src/BsMain/Api/BsApiClient.php`)
- Service token selection → Database token store: selects database (evidence: `src/BsMain/Api/OauthToken/OauthServiceTokenHandler.php`)
- Service token selection → File token store: selects file (evidence: `src/BsMain/Api/OauthToken/OauthServiceTokenHandler.php`)
- API client → Client OAuth: selects user mode (evidence: `src/BsMain/Api/BsApiClient.php`)
- Database token store → Token database: reads and writes (evidence: `src/BsMain/Api/OauthToken/OauthDatabaseServiceTokenHandler.php`)
- File token store → Persistent token file: reads and writes (evidence: `src/BsMain/Api/OauthToken/OauthFileServiceTokenHandler.php`)
- Config resolution → Vault secrets: resolves secrets (evidence: `src/BsMain/Configuration/Configuration.php`)
- Config resolution → Runtime exceptions: raises config errors (evidence: `src/BsMain/Configuration/Configuration.php`)
- Token lifecycle → Config resolution: reads settings (evidence: `src/BsMain/Api/OauthToken/OauthTokenHandler.php`)
- Typed API data → Runtime exceptions: validates data