This document is meant to be a living record of the architecture for the simpler.grants.gov system. This includes the application, network, and infrastructure architecture, as well as the CI/CD pipeline, and other services and integrations used to support the applications.
At a high level, this system uses Github to maintain the codebase repository and run the CI/CD pipeline, and AWS to host the applications and its supporting services.
This is a general software development/CI/CD diagram of the simpler.grants.gov system.
%%{init: {'theme': 'neutral' } }%%
flowchart TB
%% CI/CD Pipeline
eng["Developers fas:fa-laptop-code"] --"Push to main branch fas:fa-code-branch"--> GH
subgraph GH ["Github fab:fa-github"]
repo[Simpler Grants Repo]
click repo href "https://github.com/HHS/simpler-grants-gov" _blank
end
GH --Build and Deploys Image--> iam --> ecr
GH --Restarts task with new Image--> iam --> ECS
This is an architecture diagram focusing on the AWS shared infrastructure managed by Simpler Grants.gov. There's a write up of the same information later in the document.
Source: The Nava LucidChart by viewing "Shared With Me" > "Nava" > "Grants.gov". You can also find it at this shareable link, if you already have access.
The infrastructure is documented as a write up later in this document.
Simpler grants.gov is using the following non infrastructure shared services in AWS:
- ECS: Elastic Container Service
- ECR: Elastic Container Registry
- System Manager - Parameter Store
- Used to provide secrets and other run-time configuration options to the various services running in ECS
- Allows those inputs to be changed by re-deploying without any code changes, CI/CD etc
- Secrets Manager
- Used for database connections
- IAM: Identity and Access Management
- Cloudwatch
- Key Management Service
- Managed keys for our encryption at rest on S3 and other places
This is a diagram focusing on the CI/CD pipeline
%%{init: {'theme': 'neutral' } }%%
flowchart TD
%% CI/CD Pipeline
eng["Developers fas:fa-laptop-code"] --"Push to main branch fas:fa-code-branch"--> GH
subgraph GH ["Github fab:fa-github"]
repo[Simpler Grants Repo]
click repo href "https://github.com/HHS/simpler-grants-gov" _blank
end
subgraph AWS[HHS AWS Tenant]
ECR["AWS
Elastic Container Repository"]:::ecs
ECSS["AWS
Elastic Container Service"]:::ecs
ECR --> ECSS
end
GH --Build and deploys image--> ECR
GH --Restarts task with new image--> ECSS
classDef ecs fill:#FF9900,color:black
The "analytics" component of the application is the parts composed of the analytics service, the analytics PostgreSQL database, and Metabase. The analytics service is an ELT service that runs on AWS Step Functions via a cron trigger. At time of writing (May 2024), it collects its analytics data from GitHub. The analytics service is entirely composed of one-off tasks and does not deploy a load balancer. The analytics service extracts its data and loads it into the analytics database. The analytics database its an AWS RDS PostgreSQL database that is similar to, but distinct from, the main database that we use for our application. Metabase is a Business Intelligence dashboarding solution that we deploy. We deploy it behind a load balancer. That load balancer connects to the Metabase container. That Metabase container then connects to the analytics database, the same analytics database where the analytics ELT service is storing its data. Metabase is then configured to display charts and graphs of the data inside of the analytics database.
- CI/CD Task Runner
- Database Choices
- Front-End Language
- Front-end Framework
- Back-end Language
- Back-End Framework
- Application Infrastructure Service
- Analytics Data Storage
- Analytics Dashboard Tool
Currently a single AWS Project houses all of the environments.
AWS Cloudfront and API Gateway are deployed in front of public facing HTTPs services including the Front End and Back End Services. Access to Services is via AWS ALBs mapping to origins hosted on ECS.
Services, including FE NextJS service, BE Python API service, Metabase service, Python Analytics Service, and Simpler NOFOs Python service are all hosted as containers running on ECS clusters. These services are set to auto scale as needed to handle increases in traffic. AWS Parameter Store is used to adjust Environment Variables being passed to the services to control behavior by environment and to support feature flags defaults for the NextJS and Python API services.
Managed AWS Services are used for our data storage layer, including AWS RDS for PostgreSQL, Managed OpenSearch for search index, and AWS S3 for file storage.
The public face of the project allows HTTPS traffic from the Internet to reach the AWS Cloudfront Content Delivery Network (CDN) configured for simpler.grants.gov, training.simpler.grants.gov, etc. The CDN routes those requests to AWS Application Load Balancers (ALBs). Those ALBs route the requests to the Elastic Container Service (ECS) Clusters and Services that host the Front End code, written in NextJS.
That NextJS code can serve our static pages directly, or by making requests through to the API layer. Front End traffic from the NextJS server side code connects to the API as indicated below, even though it is hosted side-by-side the traffic flows through the publicly exposed API Gateway.
Public exposure of the API enters via the AWS API Gateway, publicly exposed on api.simpler.grants.gov, api.training.simpler.grants.gov and is routed to the ECS services that serve the API.
Publicly available files such as files attached to Opportunities, Application Instructions, etc. are accessed via a separate Cloudfront CDN (files.simpler.grants.gov) which provides access to the S3 bucket where those files are stored.
To allow for a smooth migration to the Simpler Grants system we have implemented a SOAP intermediary service that will allow data to be retrieved from both Simpler Grants and the existing Grants.gov in a backwards compatible way. This functionality is called the SOAP Notary. It is primarily expected that this functionality will be utilized by Federal Agencies who retrieve Applications for funding from Grants.gov into Grants Management systems. More details about migrating from SOAP S2S to modernized REST APIs.