america.gov

America.gov serves a static Astro site from S3 through CloudFront and runs its Bun/Hono API, SearchGov, integration-health monitor, and watchdog on ECS. PostgreSQL owns durable control and operational state, OpenSearch owns search projections, and Bedrock supplies model and embedding inference.

The repository is a Bun workspace managed with Turborepo.

Quick start

Prerequisites

• Bun 1.4.0 (specified in packageManager field of package.json)
• Git (for cloning the repository)
• Optional: Node.js 22.12.0+ (for production builds; not required for local dev)

Setup

# Clone the repository
git clone https://github.com/GSA/americagov.git
cd americagov

# Install dependencies (bypasses SSL cert issues if needed)
NODE_TLS_REJECT_UNAUTHORIZED=0 bun install

Note: If bun install fails with SSL certificate errors, use the NODE_TLS_REJECT_UNAUTHORIZED=0 prefix. This is common in corporate networks with TLS-inspecting proxies.

Running the web app

The simplest way to start the development server:

# Run the Astro web app directly (bypasses Node.js version requirement)
cd apps/web
bun --bun astro dev

This starts the web application at http://localhost:4321.

Advanced: Full development environment

For the complete local stack with API, SearchGov, and AWS services:

bun run --filter @america/web setup:dev
bun dev

The launcher prints the site URL and defaults new Portless proxies to https://america.localhost:1355. The local API consumes the accepted shared AWS SearchGov and Integration Health releases through short-lived developer access. Use bun dev:isolated for a credential-free local data plane. See docs/develop.md for the local process topology, worktrees, SearchGov, and Atlas development.

Requirements for full environment:

• AWS CLI configured with appropriate profile
• Local development secrets (managed via gitward)

Managing the dev server

# Check status
bun --bun astro dev status

# View logs
bun --bun astro dev logs

# Stop the server
bun --bun astro dev stop

Troubleshooting

Node.js version errors

If you see Node.js v20.x is not supported by Astro!:

# Use Bun's runtime instead of Node
cd apps/web
bun --bun astro dev

This bypasses the Node version check since Bun includes its own JavaScript runtime.

SSL certificate errors during install

NODE_TLS_REJECT_UNAUTHORIZED=0 bun install

Git LFS errors

If you see git-lfs: command not found during install:

• Install git-lfs: https://git-lfs.com
• Or continue without it (PII model will check out as pointer files)

Architecture

The repository separates deployable applications from shared packages:

• apps/web builds the static Astro site;
• apps/api serves the Hono API on Bun;
• apps/searchgov owns search ingestion and serving;
• apps/integrations-health and apps/integrations-health-watchdog own provider health;
• packages/ contains shared platform, product, provider, and Atlas code;
• infra/terraform is the AWS infrastructure composition root.

Atlas has one architecture: atlas-contracts owns persisted contracts, atlas-evidence owns evidence and reconciliation, runner owns Journey and Flight execution, and atlas-harness owns the operator surface. Evaluation capability belongs to those owners rather than to compatibility packages or a separate cloud runtime.

Read docs/ARCHITECTURE.md for system boundaries. The code remains the source of truth for current service and operation inventories.

Documentation

Document	Purpose
docs/ARCHITECTURE.md	System boundaries, trust model, and architecture rules
docs/VISION.md	Product intent and constraints
docs/develop.md	Local development and verification
docs/deploys.md	AWS release, delivery, and rollback invariants
docs/ci.md	CI gates and trust boundaries
docs/errors.md	Error taxonomy and operator-facing failure behavior
docs/america/infra/	AWS account, workload, and operational boundaries
docs/america/searchgov/	SearchGov architecture and operations
docs/america/integration-health.md	Health measurement and product gating
docs/atlas/	Atlas driving, evidence, review, and testing
docs/observability-aws.md	AWS telemetry, audit, and cross-account visibility
docs/postgres.md	PostgreSQL ownership and migration invariants
docs/etl.md	Reference-data loading and recovery invariants
docs/secrets-gitward.md	Encrypted local secret management

Verification

bun run lint
bun run format:check
bun run type-check
bun run test

Run the repository gates before treating a change as complete. Turbo can stop at the first failed task, so read its task summary rather than only the final exit line.

Secrets

Local values live encrypted in .gitward.json; gitward generates the ignored leaf files used by development. AWS workloads receive runtime secrets from Secrets Manager. Neither leaf files nor secret values belong in Git, Terraform outputs, release manifests, or command output. See docs/secrets-gitward.md.