### Install Dependencies and Start API

Source: https://github.com/hhs/simpler-grants-gov/blob/main/api/src/api/common_grants/COMMON_GRANTS_INTEGRATION.md

Installs project dependencies and starts the API with data seeding and log population for local development.

```bash
# Install dependencies
uv sync

# Start API with data
make init 
make db-seed-local && make populate-search-opportunities
make run-logs
```

--------------------------------

### Staging __init__.py Example

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/legacy-transforms.md

Example of an __init__.py file for the staging models directory, exporting necessary components.

```python
from .import (
    opportunity,
    example,
)

metadata = staging_base.metadata

__all__ = [
    "metadata",
    "opportunity",
    "example",
]
```

--------------------------------

### Start Database Container

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/database/database-management.md

Use 'make start-db' to start only the database container. This command is not necessary when using 'make start'.

```shell
make start-db
```

--------------------------------

### Install Dependencies with Make

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/analytics/usage.md

Use the `make install` command to verify that project dependencies are installed.

```bash
make install
```

--------------------------------

### Start Mock SOAP Services

Source: https://github.com/hhs/simpler-grants-gov/blob/main/api/mock-soap-services/README.md

Run this command in the `/api` directory to start the mock SOAP services.

```bash
make start-mock-soap-services
```

--------------------------------

### Start Local DB and Run Migrations

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/database/database-local-usage.md

Run this make command to start your local database and apply initial migrations.

```bash
make init-db
```

--------------------------------

### Start API Services

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/windows-setup.md

Starts all the necessary services after initialization is complete.

```bash
make start
```

--------------------------------

### Copy Local Environment Example (Windows)

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/frontend/development.md

Copies the example environment file to create a local environment file on Windows.

```bash
cp .env.local.example .env.local
```

--------------------------------

### Install Make and PostgreSQL Client

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/windows-setup.md

Installs the 'make' utility and 'postgresql-client' package within the Ubuntu WSL environment, which are required for project initialization and database operations.

```bash
sudo apt update
sudo apt install -y make postgresql-client
```

--------------------------------

### Example Fork Name

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/wiki/get-involved/github-code.md

An example of a correctly formatted fork name.

```bash
btabaska/1234-updating-api-with-new-header
```

--------------------------------

### Multi-Account Network Setup

Source: https://github.com/hhs/simpler-grants-gov/blob/main/docs/decisions/infra/2023-12-01-network-layer-design.md

Illustrates a multi-account setup where each environment (dev, staging, prod) has its own dedicated account and network.

```mermaid
graph RL;
  subgraph accounts
    dev_account[dev]
    staging_account[staging]
    prod_account[prod]
  end

  subgraph networks
    dev_network[dev]
    staging_network[staging]
    prod_network[prod]
  end

  subgraph environments
    dev_environment[dev]
    staging_environment[staging]
    prod_environment[prod]
  end

  dev_network --> dev_account
  staging_network --> staging_account
  prod_network --> prod_account

  dev_environment --> dev_network
  staging_environment --> staging_network
  prod_environment --> prod_network
```

--------------------------------

### Copy Local Environment Example (Mac)

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/frontend/development.md

Copies the example environment file to create a local environment file on Mac.

```bash
cp frontend/.env.local.example frontend/.env.local
```

--------------------------------

### Initialize S3 Mock Service

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/development.md

Run this command to start the S3Mock service for local development.

```bash
make init-s3mock
```

--------------------------------

### Install PostgreSQL Client

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/windows-setup.md

Installs the PostgreSQL client utilities on Debian-based systems, necessary for certain database interaction scripts.

```bash
sudo apt install -y postgresql-client
```

--------------------------------

### Install Infrastructure Linters

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-infrastructure-tools.md

Installs several optional infrastructure linter utilities (Shellcheck, actionlint, lychee) using Homebrew for local testing.

```bash
brew install shellcheck
brew install actionlint
brew install lychee
```

--------------------------------

### Install WSL 2 with Ubuntu

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/windows-setup.md

Installs WSL 2 with Ubuntu distribution. This is a prerequisite for the API development setup.

```powershell
wsl --install -d Ubuntu
```

```powershell
wsl --install Ubuntu
```

--------------------------------

### Test File Naming Convention

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/analytics/testing.md

Test files must start with the 'test_' prefix, followed by the name of the module they cover. For example, tests for 'foo.py' should be in 'test_foo.py'.

```python
# Example: tests for analytics/src/analytics/datasets/base.py
# would be in analytics/tests/datasets/test_base.py
```

--------------------------------

### Display a success alert with next steps

Source: https://github.com/hhs/simpler-grants-gov/blob/main/frontend/stories/brand/tone.mdx

Use the `Alert` component with `type='success'` and `slim` props to confirm a user's ability to perform tasks after meeting certain criteria. This example guides users on next steps.

```javascript
import { Alert } from "@trussworks/react-uswds";

<Alert type="success" slim>
  Once your Point of Contact (POC) links you to the agency and assigns you the
  appropriate roles, you'll be able to complete tasks in Grants.gov. Let your
  agency POC know after you register.
</Alert>
```

--------------------------------

### Initialize OpenSearch Service

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/development.md

Run this command to set up the OpenSearch container for local development.

```bash
make init-opensearch
```

--------------------------------

### Install Specific Terraform Version

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-infrastructure-tools.md

Installs a specific version of Terraform using tfenv. Ensure you have tfenv installed first.

```bash
tfenv install 1.4.6
```

--------------------------------

### Create and Navigate to Project Folder

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/wiki/product/api/simpler-grants-api-tutorial/lets-make-a-python-script-to-use-the-api/make-a-project-folder.md

Use these bash commands to create a new directory for your project and then move into it. This sets up the base environment for your script.

```bash
mkdir sgg-quickstart
cd sgg-quickstart
```

--------------------------------

### Set Up AWS Account Backend Resources

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-aws-account.md

This command initiates the creation of the S3 tfstate bucket and the GitHub OIDC provider. It also generates a backend configuration file. Replace <ACCOUNT_NAME> with a descriptive name for your AWS account.

```bash
make infra-set-up-account ACCOUNT_NAME=<ACCOUNT_NAME>
```

--------------------------------

### Form Schema Example

Source: https://github.com/hhs/simpler-grants-gov/blob/main/frontend/src/components/applyForm/README.md

Example of a form schema definition for a string field.

```json

"properties": {
   "TestField": {
      "type": "string",
      "title": "Date of application ",
      "description": "This will be overwritten the by the schema.description entry above"
      "format": "date"
  }
}


```

--------------------------------

### Start Docker Services

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/analytics/run-metabase-on-apple-silicon.md

Starts all defined Docker Compose services in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Run setup-foreign-tables Command

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/legacy-transforms.md

Execute the setup-foreign-tables command using a make target. Ensure the migrator role has necessary database permissions. Replace <environment> with your target environment.

```sh
make release-run-setup-foreign-tables APP_NAME=api ENVIRONMENT=<environment>
```

--------------------------------

### Seed Database with Sample Data

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/windows-setup.md

Populates the database with sample opportunities and agencies, and indexes searchable data in OpenSearch. Recommended for initial setup.

```bash
make setup-api-data
```

--------------------------------

### Start Docker Services

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/analytics/development.md

Use this command to start the analytics services in detached mode.

```bash
cd simpler-grants-gov/analytics
docker-compose up -d
```

--------------------------------

### Initialize Mock OAuth2 Server

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/development.md

Run this command to set up the mock OAuth2 server for local development.

```bash
make init-mock-oauth2
```

--------------------------------

### JSON Log Format Example

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/monitoring-and-observability/logging-configuration.md

Example of a log message formatted as JSON. This format is machine-readable and is the default.

```json
{
    "name": "src.api.healthcheck",
    "levelname": "INFO",
    "funcName": "healthcheck_get",
    "created": "1663261542.0465896",
    "thread": "275144058624",
    "threadName": "Thread-2 (process_request_thread)",
    "process": "16",
    "message": "GET /v1/healthcheck",
    "request.method": "GET",
    "request.path": "/v1/healthcheck",
    "request.url_rule": "/v1/healthcheck",
    "request_id": ""
}
```

--------------------------------

### Install GitHub CLI

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-infrastructure-tools.md

Installs the GitHub CLI using Homebrew. This tool is useful for automating GitHub operations.

```bash
brew install gh
```

--------------------------------

### Using the Mock SAM.gov Client

Source: https://github.com/hhs/simpler-grants-gov/blob/main/api/src/adapters/sam_gov/README.md

Illustrates two methods for enabling the mock SAM.gov client for local development and testing: via an environment variable or a configuration object.

```python
# Method 1: Environment variable
import os
os.environ["SAM_GOV_USE_MOCK"] = "true"
client = create_sam_gov_client()

# Method 2: Config object
from src.adapters.sam_gov import create_sam_gov_client, SamGovConfig

config = SamGovConfig(use_mock=True)
client = create_sam_gov_client(config=config)
```

--------------------------------

### Install Ubuntu WSL Distribution

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/windows-setup.md

Use this command to install the Ubuntu distribution for WSL if it's not already present on your system.

```powershell
wsl --install Ubuntu
```

--------------------------------

### Configure Network Backend

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-network.md

Run this command to create the tfbackend file for the new application environment.

```bash
make infra-configure-network
```

--------------------------------

### Configure backend for app build repository

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-app-build-repository.md

Run this command to create the tfbackend file for the build repository. Specify the app folder name using APP_NAME.

```bash
make infra-configure-app-build-repository APP_NAME=app
```

--------------------------------

### Verify Docker Installation in WSL

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/windows-setup.md

Checks if Docker and Docker Compose are installed and accessible within the Ubuntu WSL environment.

```bash
docker --version
docker compose version
```

--------------------------------

### Python Workflow Configuration Example

Source: https://github.com/hhs/simpler-grants-gov/blob/main/api/src/workflow/README.md

Sets up the configuration for a workflow, including type, persistence model, and entity type.

```python
from src.workflow.workflow_config import ApprovalConfig, WorkflowConfig

example_config = WorkflowConfig(
    # The workflow type needs to be added to the enum
    # This is used as an easy means to find the workflow
    # class and start / reference a workflow of a given type.
    workflow_type=WorkflowType.EXAMPLE,
    # This class handles persisting the entity to the database
    # for you automatically. If the entity type you need isn't
    # defined, see the "Add a new entity type" section below
    persistence_model_cls=OpportunityPersistenceModel,
    entity_type=WorkflowEntityType.OPPORTUNITY,
    # Whether to allow a given entity to have more than one
    # active version of a workflow at a time. Defaults to True.
    allow_concurrent_workflow_for_entity=False,
    approval_mapping={
        # See below for details on adding approvals
        # which need a few pieces of configuration
        # in order to setup.
    }
)
```

--------------------------------

### Configure Backend for App Database

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-database.md

Run this command to create the tfbackend file for a new application environment. Ensure APP_NAME and ENVIRONMENT are correctly set.

```bash
make infra-configure-app-database APP_NAME=<APP_NAME> ENVIRONMENT=<ENVIRONMENT>
```

--------------------------------

### Create Database Resources

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-database.md

Execute this command to provision the necessary database resources. Review the Terraform plan before applying. This process may take over 5 minutes.

```bash
make infra-update-app-database APP_NAME=app ENVIRONMENT=<ENVIRONMENT>
```

--------------------------------

### Terraform Backend Configuration Example

Source: https://github.com/hhs/simpler-grants-gov/blob/main/infra/README.md

Illustrates how backend configuration files are named for different environments and shared resources.

```text
dev.s3.tfbackend
```

```text
shared.s3.tfbackend
```

```text
<account name>.<account id>.s3.tfbackend
```

--------------------------------

### Install Terraform Version Manager

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-infrastructure-tools.md

Installs Terraform Version Manager (tfenv) using Homebrew for managing multiple Terraform versions.

```bash
brew install tfenv
```

--------------------------------

### Initialize SQS Mock Service

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/api/development.md

Run this command to start the elasticmq (local SQS) service for local development.

```bash
make init-sqsmock
```

--------------------------------

### Install grants_shared Package

Source: https://github.com/hhs/simpler-grants-gov/blob/main/backend/grants_shared/README.md

Install the grants_shared package using common Python dependency managers like pip, poetry, or uv.

```shell
# Using pip
pip install grants_shared

# Using poetry
poetry add grants_shared

# Using uv
uv add grants_shared
```

--------------------------------

### Run Storybook Natively

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/frontend/development.md

Start the Storybook development server locally to build and test components in isolation. Navigate to the specified URL to view the Storybook interface.

```bash
npm run storybook
```

--------------------------------

### Build Application for Release

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/set-up-app-env.md

Run this command from the root directory to build the application for release. This can be a time-consuming process depending on your machine's architecture.

```bash
make release-build
```

--------------------------------

### GetOpportunityList Response Example

Source: https://github.com/hhs/simpler-grants-gov/blob/main/api/mock-soap-services/README.md

This is an example of a successful response from the 'GetOpportunityList' operation. Note that some values, like 'OpeningDate', may be randomized on subsequent requests.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header/>
<env:Body>
    <app:GetOpportunityListResponse xmlns:app="http://apply.grants.gov/services/ApplicantWebServices-V2.0" xmlns:app1="http://apply.grants.gov/system/ApplicantCommonElements-V1.0" xmlns:gran="http://apply.grants.gov/system/GrantsCommonElements-V1.0">
    <app1:OpportunityDetails>
        <gran:FundingOpportunityNumber>string</gran:FundingOpportunityNumber>
        <gran:FundingOpportunityTitle>string</gran:FundingOpportunityTitle>
        <gran:CompetitionID>string</gran:CompetitionID>
        <gran:CompetitionTitle>string</gran:CompetitionTitle>
        <gran:PackageID>string</gran:PackageID>
        <app1:CFDADetails>
        <app1:Number>string</app1:Number>
        <app1:Title>string</app1:Title>
        </app1:CFDADetails>
        <app1:OpeningDate>2014-06-14+00:00</app1:OpeningDate>
        <app1:ClosingDate>2004-12-26</app1:ClosingDate>
        <gran:OfferingAgency>string</gran:OfferingAgency>
        <gran:AgencyContactInfo>string</gran:AgencyContactInfo>
        <gran:SchemaURL>string</gran:SchemaURL>
        <gran:InstructionsURL>string</gran:InstructionsURL>
        <app1:IsMultiProject>true</app1:IsMultiProject>
    </app1:OpportunityDetails>
    </app:GetOpportunityListResponse>
</env:Body>
</env:Envelope>
```

--------------------------------

### Test Case Naming Convention

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/analytics/testing.md

Test functions or methods must start with the 'test_' prefix. For test classes, the class name should start with 'Test'.

```python
# Example test function
def test_to_and_from_csv():
    pass

# Example test class and method
class TestSprintBoard:
    def test_scenario_one(self):
        pass
```

--------------------------------

### Run Tests for the Database Module

Source: https://github.com/hhs/simpler-grants-gov/blob/main/documentation/infra/terraform-unit-testing.md

Example of running tests for the 'database' module, demonstrating the single module test execution command.

```bash
terraform -chdir=infra/modules/database init -backend=false
terraform -chdir=infra/modules/database test
```