From 8fc95ca1ea2544c7b942c7d7605cd89daa2f62c0 Mon Sep 17 00:00:00 2001 From: "Stephen A. Fuqua" Date: Wed, 15 Jan 2025 13:57:23 -0600 Subject: [PATCH] Initial draft diagrams --- .../adminconsole/APIS-FOR-ADMIN-CONSOLE.md | 3 + .../adminconsole/HEALTH-CHECK-WORKER.md | 3 + .../adminconsole/INSTANCE-MANAGEMENT.md | 3 + docs/design/adminconsole/readme.md | 131 ++++++++++++++++++ 4 files changed, 140 insertions(+) create mode 100644 docs/design/adminconsole/APIS-FOR-ADMIN-CONSOLE.md create mode 100644 docs/design/adminconsole/HEALTH-CHECK-WORKER.md create mode 100644 docs/design/adminconsole/INSTANCE-MANAGEMENT.md create mode 100644 docs/design/adminconsole/readme.md diff --git a/docs/design/adminconsole/APIS-FOR-ADMIN-CONSOLE.md b/docs/design/adminconsole/APIS-FOR-ADMIN-CONSOLE.md new file mode 100644 index 000000000..dfb12ca21 --- /dev/null +++ b/docs/design/adminconsole/APIS-FOR-ADMIN-CONSOLE.md @@ -0,0 +1,3 @@ +# REST API Support for Admin Console + +placeholder diff --git a/docs/design/adminconsole/HEALTH-CHECK-WORKER.md b/docs/design/adminconsole/HEALTH-CHECK-WORKER.md new file mode 100644 index 000000000..73a71bcad --- /dev/null +++ b/docs/design/adminconsole/HEALTH-CHECK-WORKER.md @@ -0,0 +1,3 @@ +# Health Check Worker + +placeholder diff --git a/docs/design/adminconsole/INSTANCE-MANAGEMENT.md b/docs/design/adminconsole/INSTANCE-MANAGEMENT.md new file mode 100644 index 000000000..2bddfd5e5 --- /dev/null +++ b/docs/design/adminconsole/INSTANCE-MANAGEMENT.md @@ -0,0 +1,3 @@ +# Instance Management Worker + +Placeholder diff --git a/docs/design/adminconsole/readme.md b/docs/design/adminconsole/readme.md new file mode 100644 index 000000000..9d3ecef8e --- /dev/null +++ b/docs/design/adminconsole/readme.md @@ -0,0 +1,131 @@ +# Admin API Design to Support the Admin Console + +## Overview + +The Ed-Fi Admin Console is a web-based user interface tool for managing Ed-Fi +ODS/API Platform installations. User can perform actions that include: + +* Manage tenants and database instances +* Manage Client credentials ("keys and secrets") +* Review application and database health + +The Ed-Fi Admin Console application is a front-end only. The Ed-Fi Admin API 2 +application will act as the backend-for-frontend (BFF), serving all of the +interaction needs for Admin Console. The Ed-Fi Admin API 2 will in turn rely on +other services and "worker" applications as needed to achieve some of its goals. + +The purpose of this document and related documents is to describe the +architecture of the related applications, the interfaces that sustain +communication, and the storage layers requirements. + +> [!TIP] +> The following sections utilize the [C4 model](https://c4model.com/) for +> describing the System Context and decomposing Containers within that Context. +> The notes further refine the architecture with detailed [UML sequence +> diagrams](https://en.wikipedia.org/wiki/Sequence_diagram). + +## System Context + +```mermaid +C4Context + title System Context for Ed-Fi Admin Console + + Person(User, "Admin Console User", "A system administrator") + + System(AdminConsole, "Ed-Fi Admin Console", "A web application for managing ODS/API Deployments") + + System_Boundary(backend, "Backend Systems") { + + System(AdminAPI, "Ed-Fi Admin API 2 and Workers", "A REST API system for managing administrative data and deployments, plus background worker apps") + + System(OdsApi, "Ed-Fi ODS/API", "A REST API system for educational data interoperability") + SystemDb(dbs, "ODS, Admin, and Security") + } + + Rel(User, AdminConsole, "Manages instances,
Manages client credentials,
Checks API health") + UpdateRelStyle(User, AdminConsole, $offsetX="0", $offsetY="30") + + Rel(AdminConsole, AdminAPI, "Issues HTTP requests") + UpdateRelStyle(AdminConsole, AdminAPI, $offsetY="-40", $offsetX="20") + + Rel(AdminAPI, dbs, "Reads and writes admin/security,
Creates ODS instances") + UpdateRelStyle(AdminAPI, dbs, $offsetY="0", $offsetX="40") + + Rel(AdminAPI, OdsApi, "Reads") + UpdateRelStyle(AdminAPI, OdsApi, $offsetY="-10", $offsetX="-10") + + Rel(OdsApi, dbs, "Reads admin and writes ODS") + UpdateRelStyle(OdsApi, dbs, $offsetY="10", $offsetX="80") + + UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1") +``` + +## Containers + +Two of the functions needed by Admin API 2 will benefit from background +execution, so that the Admin Console end user can experience a quick response +time in the web browser. Two worker applications will provide the background +processing: + +1. Instance Management Worker - creates new database instances. +2. Health Check Worker - polls the ODS/API to find record counts and records + them in Admin API 2. + +```mermaid +C4Container + title "Admin API Containers" + + System(AdminConsole, "Ed-Fi Admin Console", "A web application for managing ODS/API Deployments") + + System_Boundary(backend, "Backend Systems") { + + Boundary(b0, "Admin API") { + Container(AdminAPI, "Ed-Fi Admin API 2") + Container(HealthCheck, "Admin API Health
Check Worker") + Container(Instance, "Admin API Instance
Management Worker") + } + + Boundary(b1, "ODS/API") { + System(OdsApi, "Ed-Fi ODS/API", "A REST API system for
educational data interoperability") + SystemDb(ods3, "EdFi_ODS_") + } + + Boundary(b2, "Shared Databases") { + ContainerDb(Admin, "EdFi_Admin,
EdFi_Security") + } + } + + Rel(AdminConsole, AdminAPI, "Issues HTTP requests") + + Rel(HealthCheck, AdminAPI, "Reads ODS/API connections,
Writes health info") + UpdateRelStyle(HealthCheck, AdminAPI, $offsetY="50") + + Rel(HealthCheck, OdsApi, "Reads records counts") + UpdateRelStyle(HealthCheck, OdsApi, $offsetX="-60", $offsetY="20") + + Rel(Instance, AdminAPI, "Reads instance requests,
Write instance status") + UpdateRelStyle(Instance, AdminAPI, $offsetY="20", $offsetX="10") + + Rel(Instance, ods3, "Creates new ODS instances") + UpdateRelStyle(Instance, ods3, $offsetY="20", $offsetX="-50") + + Rel(OdsApi, ods3, "Reads and writes") + UpdateRelStyle(OdsApi, ods3, $offsetX="10") + + Rel(AdminAPI, Admin, "Reads and writes") + UpdateRelStyle(AdminAPI, Admin, $offsetY="50", $offsetX="10") + + Rel(OdsApi, Admin, "Reads") + UpdateRelStyle(OdsApi, Admin, $offsetY="20", $offsetX="-10") + + UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2") +``` + +## Interfaces and Interactions + +The API interfaces and the interactions between specific containers are +described in detail in the following documents: + +* [Instance Management Worker](./INSTANCE-MANAGEMENT.md) +* [Health Check Worker](./HEALTH-CHECK-WORKER.md) +* [REST API Support for Admin Console](./APIS-FOR-ADMIN-CONSOLE.md)