How hhs/simpler-grants-gov works
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: services Domain Services · infra Infra Stacks · app Frontend App · api BFF Routes
Components 24
Frontend
Public Next.js app and browser-facing BFF routes.
- Frontend App · Public-facing UI with App Router, i18n, and server-side routes.
frontend/src/app - BFF Routes · Browser-facing proxy/session/auth and domain action handlers under app/api.
frontend/src/app/api - Search UI · Opportunity discovery, filtering, saving, and export experience.
frontend/src/app/[locale]/(base)/search - Workspace UI · Applications, organizations, saved opportunities, and settings.
frontend/src/app/[locale]/(base)/workspace - Apply Forms · Client-side application form rendering and submission UX.
frontend/src/components/apply-form
Primary API
Main Flask service and its domain subsystems.
- Flask API · Main product backend exposing core grants domains.
api/src/app.py - Auth Layer · Login.gov, internal JWT, API keys, and endpoint access control.
api/src/auth - Domain Services · Application, opportunity, user, organization, award, and workflow services.
api/src/services - API Blueprints · Flask blueprints for public, grantor, internal, and legacy endpoints.
api/src/api - Form Schema · Form registry, rules, validation, and XML/schema generation inputs.
api/src/form_schema - XML Pipeline · Transforms application data into validated submission XML.
api/src/services/xml_generation - Legacy SOAP · SOAP-compatible proxy and legacy grants.gov interfaces.
api/src/legacy_soap_api - Postgres Models · SQLAlchemy models plus Alembic migrations for the main RDS database.
api/src/db - Search Indexing · OpenSearch query and indexing support for opportunity search.
api/src/search - File Subsystem · Presigned uploads, scan tracking, S3/DynamoDB state, and quarantine flow.
api/src/services/files - Background Tasks · Scheduled and queued work for notifications, publishing, extracts, and maintenance.
api/src/task - Workflow Engine · Event-driven workflow processing and approval orchestration.
api/src/workflow
Analytics
Separate ETL/reporting application.
- Analytics App · Separate reporting and ETL application feeding dashboards.
analytics/src/analytics - Metabase Data · 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 · Smaller grants management API with healthcheck, DB, and task surface.
backend/grants_management_api/src - Shared Lib · 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 · Environment-specific Terraform for all deployed services and shared AWS foundations.
infra - Terraform Modules · 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 · GitHub Actions, release automation, migrations, and local operational scripts.
Connections 29
- 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.