# hhs/simpler-grants-gov architecture

> Architecture diagram of the GitHub repository hhs/simpler-grants-gov, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hhs/simpler-grants-gov
- Repository: https://github.com/hhs/simpler-grants-gov

## Overview

1. This is a monorepo for a federal grants platform with multiple deployable surfaces: a public-facing Next.js frontend, a primary Flask API, a separate analytics service, infrastructure-as-code, and supporting shared libraries and operational scripts.

2. The main user-facing entry point is `frontend/`. It is a Next.js app using the App Router, internationalization, and server-side route handlers under `src/app/api`. Those handlers act as a BFF/proxy layer for browser requests, session/auth flows, and some domain actions, rather than having the browser talk directly to every backend dependency.

3. The primary application backend is `api/`, a large Flask service organized by blueprints, routes, services, adapters, and tasks. It exposes the core product domains: opportunities/search, applications and form submission, users and organizations, award recommendations, workflows, files, extracts, and legacy SOAP compatibility.

4. The main persistent data store is PostgreSQL/RDS, with schema managed through Alembic migrations and SQLAlchemy models in `api/src/db/models`. The API also uses DynamoDB for file-scan/cache style state, S3 for uploaded/generated files and extracts, OpenSearch for searchable opportunity data, and SQS for asynchronous job/event processing.

5. Major data flows center on grants workflows:
   - opportunity discovery/search flows from database-backed opportunity data into OpenSearch, then into the frontend search UI;
   - application submission flows from the frontend into the API, through form-schema processing, XML generation, validation, and database persistence;
   - grantor/opportunity management flows allow internal users to create/update/publish opportunities and competition data.

6. File handling is a distinct subsystem. The API generates presigned uploads, tracks pending scans, and integrates with file-scanning infrastructure. The infra includes ClamAV-related modules and separate file-scan cache resources, which indicates uploaded files are quarantined/validated before becoming usable.

7. Authentication and identity are split across several boundaries. The frontend supports login/session handling, while the API has multiple auth mechanisms: Login.gov OAuth/JWT, internal JWT, API user keys, and endpoint-level access control. The infrastructure also provisions identity-provider resources and secrets needed for these flows.

8. There are several important external integrations: SAM.gov data, legacy SOAP services, SES/email notifications, New Relic logging/monitoring, and PDF generation. The API contains dedicated adapters and service packages for these integrations, plus a legacy SOAP proxy layer that preserves older grants.gov-compatible interfaces.

9. Background work is a first-class part of the architecture. The API has a task framework and many task modules for notifications, opportunity publishing/versioning, SAM extract processing, form version locking, analytics exports, and internal maintenance. These tasks run separately from request/response traffic and are wired through AWS jobs/schedulers in infra.

10. `analytics/` is a separate Python application focused on reporting and ETL. It pulls from GitHub/project data sources, loads into an ETL database, and powers Metabase dashboards. It is operationally separate from the product API and frontend.

11. `backend/grants_management_api/` is a smaller additional Flask service with its own shared package in `backend/grants_shared/`. It has a thinner surface than `api/`, but follows the same general pattern: Flask app, database models, tasks, and shared AWS/database abstractions.

12. `infra/` defines the runtime boundary for everything above. It is heavily modular Terraform organized by service and environment (`dev`, `staging`, `prod`, `training`, grantee-specific variants), with separate modules for network, database, search, storage, notifications, identity provider, monitoring, WAF, and service deployment. The architecture is clearly AWS-centered, with build repositories, app-config layers, and environment-specific service definitions.

13. Operationally, the repo is managed through GitHub Actions and supporting scripts. Workflows cover CI, e2e, vulnerability scanning, deployments, database migrations, infra checks, and release automation, which matters because the system is deployed as multiple coordinated services rather than a single application.

Main entry points: [`api/src/services`](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/services) (Domain Services), [`infra`](https://github.com/hhs/simpler-grants-gov/tree/main/infra) (Infra Stacks), [`frontend/src/app`](https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app) (Frontend App), [`frontend/src/app/api`](https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app/api) (BFF Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Frontend App<br/>Next.js app"]
  node_frontend_bff["BFF Routes<br/>route handlers"]
  node_frontend_search["Search UI<br/>search surface"]
  node_frontend_workspace["Workspace UI<br/>account surface"]
  node_frontend_apply["Apply Forms<br/>form engine"]
end

subgraph group_api["Primary API"]
  node_api_app["Flask API<br/>primary service<br/>[app.py]"]
  node_api_auth["Auth Layer<br/>auth mechanisms"]
  node_api_domain["Domain Services<br/>service layer"]
  node_api_api["API Blueprints<br/>routes"]
  node_api_form["Form Schema<br/>schema engine"]
  node_api_xml["XML Pipeline<br/>submission xml"]
  node_api_legacy["Legacy SOAP<br/>compatibility layer"]
  node_api_db[("Postgres Models<br/>persistence")]
  node_api_search["Search Indexing<br/>search backend"]
  node_api_files["File Subsystem<br/>upload/scan"]
  node_api_tasks["Background Tasks<br/>async jobs"]
  node_api_workflow["Workflow Engine<br/>state machine"]
end

subgraph group_analytics["Analytics"]
  node_analytics_app["Analytics App<br/>Python ETL"]
  node_analytics_metabase["Metabase Data<br/>dashboard layer"]
end

subgraph group_backend["Secondary backend"]
  node_backend_api["Mgmt API<br/>Flask service"]
  node_backend_shared["Shared Lib<br/>common package"]
end

subgraph group_infra["Infrastructure"]
  node_infra_root["Infra Stacks<br/>terraform mono-repo"]
  node_infra_modules["Terraform Modules<br/>module library"]
end

subgraph group_ops["Operations"]
  node_ops_ci["CI/CD Ops<br/>workflows and scripts"]
end

node_frontend_app -->|"serves via"| node_frontend_bff
node_frontend_app -->|"contains"| node_frontend_search
node_frontend_app -->|"contains"| node_frontend_workspace
node_frontend_app -->|"uses"| node_frontend_apply
node_frontend_bff -->|"calls"| node_api_api
node_frontend_search -->|"queries"| node_frontend_bff
node_frontend_workspace -->|"mutates via"| node_frontend_bff
node_frontend_apply -->|"submits via"| node_frontend_bff
node_api_app -->|"configures"| node_api_auth
node_api_app -->|"mounts"| node_api_api
node_api_api -->|"delegates to"| node_api_domain
node_api_domain -->|"persists to"| node_api_db
node_api_domain -->|"uses"| node_api_form
node_api_domain -->|"generates"| node_api_xml
node_api_domain -->|"handles"| node_api_files
node_api_domain -->|"indexes/searches"| node_api_search
node_api_domain -->|"dispatches"| node_api_tasks
node_api_domain -->|"orchestrates"| node_api_workflow
node_api_legacy -->|"bridges to"| node_api_domain
node_analytics_app -->|"feeds"| node_analytics_metabase
node_backend_api -->|"depends on"| node_backend_shared
node_infra_root -->|"composes"| node_infra_modules
node_infra_root -->|"deploys"| node_api_app
node_infra_root -->|"deploys"| node_frontend_app
node_infra_root -->|"deploys"| node_analytics_app
node_infra_root -->|"deploys"| node_backend_api
node_ops_ci -->|"automates"| node_infra_root
node_ops_ci -->|"schedules"| node_api_tasks
node_ops_ci -->|"runs"| node_analytics_app

click node_frontend_app "https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app"
click node_frontend_bff "https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app/api"
click node_frontend_search "https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app/[locale]/(base)/search"
click node_frontend_workspace "https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app/[locale]/(base)/workspace"
click node_frontend_apply "https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/components/apply-form"
click node_api_app "https://github.com/hhs/simpler-grants-gov/blob/main/api/src/app.py"
click node_api_auth "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/auth"
click node_api_domain "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/services"
click node_api_api "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/api"
click node_api_form "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/form_schema"
click node_api_xml "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/services/xml_generation"
click node_api_legacy "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/legacy_soap_api"
click node_api_db "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/db"
click node_api_search "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/search"
click node_api_files "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/services/files"
click node_api_tasks "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/task"
click node_api_workflow "https://github.com/hhs/simpler-grants-gov/tree/main/api/src/workflow"
click node_analytics_app "https://github.com/hhs/simpler-grants-gov/tree/main/analytics/src/analytics"
click node_analytics_metabase "https://github.com/hhs/simpler-grants-gov/tree/main/analytics/src/analytics/integrations/metabase"
click node_backend_api "https://github.com/hhs/simpler-grants-gov/tree/main/backend/grants_management_api/src"
click node_backend_shared "https://github.com/hhs/simpler-grants-gov/tree/main/backend/grants_shared/src/grants_shared"
click node_infra_root "https://github.com/hhs/simpler-grants-gov/tree/main/infra"
click node_infra_modules "https://github.com/hhs/simpler-grants-gov/tree/main/infra/modules"

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_frontend_app,node_frontend_bff,node_frontend_search,node_frontend_workspace,node_frontend_apply toneBlue
class node_api_app,node_api_auth,node_api_domain,node_api_api,node_api_form,node_api_xml,node_api_legacy,node_api_db,node_api_search,node_api_files,node_api_tasks,node_api_workflow toneAmber
class node_analytics_app,node_analytics_metabase toneMint
class node_backend_api,node_backend_shared toneRose
class node_infra_root,node_infra_modules toneIndigo
class node_ops_ci toneTeal
```

## Components

### Frontend

Public Next.js app and browser-facing BFF routes.

- [Frontend App](https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app): Next.js app · Public-facing UI with App Router, i18n, and server-side routes. · `frontend/src/app`
- [BFF Routes](https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app/api): route handlers · Browser-facing proxy/session/auth and domain action handlers under app/api. · `frontend/src/app/api`
- [Search UI](https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app/[locale]/(base)/search): search surface · Opportunity discovery, filtering, saving, and export experience. · `frontend/src/app/[locale]/(base)/search`
- [Workspace UI](https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/app/[locale]/(base)/workspace): account surface · Applications, organizations, saved opportunities, and settings. · `frontend/src/app/[locale]/(base)/workspace`
- [Apply Forms](https://github.com/hhs/simpler-grants-gov/tree/main/frontend/src/components/apply-form): form engine · Client-side application form rendering and submission UX. · `frontend/src/components/apply-form`

### Primary API

Main Flask service and its domain subsystems.

- [Flask API](https://github.com/hhs/simpler-grants-gov/blob/main/api/src/app.py): primary service · Main product backend exposing core grants domains. · `api/src/app.py`
- [Auth Layer](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/auth): auth mechanisms · Login.gov, internal JWT, API keys, and endpoint access control. · `api/src/auth`
- [Domain Services](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/services): service layer · Application, opportunity, user, organization, award, and workflow services. · `api/src/services`
- [API Blueprints](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/api): routes · Flask blueprints for public, grantor, internal, and legacy endpoints. · `api/src/api`
- [Form Schema](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/form_schema): schema engine · Form registry, rules, validation, and XML/schema generation inputs. · `api/src/form_schema`
- [XML Pipeline](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/services/xml_generation): submission xml · Transforms application data into validated submission XML. · `api/src/services/xml_generation`
- [Legacy SOAP](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/legacy_soap_api): compatibility layer · SOAP-compatible proxy and legacy grants.gov interfaces. · `api/src/legacy_soap_api`
- [Postgres Models](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/db): persistence · SQLAlchemy models plus Alembic migrations for the main RDS database. · `api/src/db`
- [Search Indexing](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/search): search backend · OpenSearch query and indexing support for opportunity search. · `api/src/search`
- [File Subsystem](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/services/files): upload/scan · Presigned uploads, scan tracking, S3/DynamoDB state, and quarantine flow. · `api/src/services/files`
- [Background Tasks](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/task): async jobs · Scheduled and queued work for notifications, publishing, extracts, and maintenance. · `api/src/task`
- [Workflow Engine](https://github.com/hhs/simpler-grants-gov/tree/main/api/src/workflow): state machine · Event-driven workflow processing and approval orchestration. · `api/src/workflow`

### Analytics

Separate ETL/reporting application.

- [Analytics App](https://github.com/hhs/simpler-grants-gov/tree/main/analytics/src/analytics): Python ETL · Separate reporting and ETL application feeding dashboards. · `analytics/src/analytics`
- [Metabase Data](https://github.com/hhs/simpler-grants-gov/tree/main/analytics/src/analytics/integrations/metabase): dashboard layer · ETL database and Metabase-oriented SQL/reporting assets. · `analytics/src/analytics/integrations/metabase`

### Secondary backend

Smaller grants management Flask service and shared package.

- [Mgmt API](https://github.com/hhs/simpler-grants-gov/tree/main/backend/grants_management_api/src): Flask service · Smaller grants management API with healthcheck, DB, and task surface. · `backend/grants_management_api/src`
- [Shared Lib](https://github.com/hhs/simpler-grants-gov/tree/main/backend/grants_shared/src/grants_shared): common package · Reusable AWS, DB, API, logging, pagination, and utility abstractions. · `backend/grants_shared/src/grants_shared`

### Infrastructure

Terraform modules and environment stacks for AWS deployment.

- [Infra Stacks](https://github.com/hhs/simpler-grants-gov/tree/main/infra): terraform mono-repo · Environment-specific Terraform for all deployed services and shared AWS foundations. · `infra`
- [Terraform Modules](https://github.com/hhs/simpler-grants-gov/tree/main/infra/modules): module library · Reusable modules for service, database, storage, search, identity, notifications, network, and monitoring. · `infra/modules`

### Operations

CI/CD workflows, scripts, and local/test harnesses.

- **CI/CD Ops**: workflows and scripts · GitHub Actions, release automation, migrations, and local operational scripts.

## Connections

- Frontend App → BFF Routes: serves via · UI depends on route handlers for auth, proxy, and domain actions.
- Frontend App → Search UI: contains · Search is a major user-facing surface.
- Frontend App → Workspace UI: contains · Workspace covers account and collaboration flows.
- Frontend App → Apply Forms: uses · Application submission UI is built from shared form components.
- BFF Routes → API Blueprints: calls · Browser requests are mediated through API endpoints.
- Search UI → BFF Routes: queries · Search UI fetches through the BFF layer.
- Workspace UI → BFF Routes: mutates via · Workspace actions go through route handlers.
- Apply Forms → BFF Routes: submits via · Form data and file actions are sent through the BFF.
- Flask API → Auth Layer: configures · The Flask app wires multiple authentication strategies.
- Flask API → API Blueprints: mounts · Blueprints provide the HTTP surface.
- API Blueprints → Domain Services: delegates to · Routes call service-layer functions rather than embedding logic.
- Domain Services → Postgres Models: persists to · Core domain state is stored in PostgreSQL via SQLAlchemy.
- Domain Services → Form Schema: uses · Application and competition flows rely on form schema processing.
- Domain Services → XML Pipeline: generates · Submission flows produce XML from structured form data.
- Domain Services → File Subsystem: handles · Domain logic coordinates uploads, scans, and attachments.
- Domain Services → Search Indexing: indexes/searches · Opportunity data is exposed through OpenSearch-backed search.
- Domain Services → Background Tasks: dispatches · Long-running work and notifications are run asynchronously.
- Domain Services → Workflow Engine: orchestrates · Workflow events and approval state are managed separately.
- Legacy SOAP → Domain Services: bridges to · SOAP compatibility proxies into modern service logic.
- Analytics App → Metabase Data: feeds · ETL outputs populate reporting tables and dashboards.
- Mgmt API → Shared Lib: depends on · The secondary service reuses shared abstractions.
- Infra Stacks → Terraform Modules: composes · Environment stacks are built from reusable Terraform modules.
- Infra Stacks → Flask API: deploys · Infra defines runtime and environment wiring for the main API.
- Infra Stacks → Frontend App: deploys · Infra defines runtime and environment wiring for the frontend.
- Infra Stacks → Analytics App: deploys · Infra provisions the analytics service and its database.
- Infra Stacks → Mgmt API: deploys · Infra also includes the smaller grants management API.
- CI/CD Ops → Infra Stacks: automates · GitHub Actions and scripts drive Terraform and deployment workflows.
- CI/CD Ops → Background Tasks: schedules · Operational jobs trigger background task execution.
- CI/CD Ops → Analytics App: runs · CI and release flows build and ship the analytics service.
