This repo is a proof of concept of a mobile-first ledger for self employed workers to verify their income and expenses related to their self employment.

This application is uses:

• NextJS
• React
• USWDS react components
• Deployment to cloud.gov

An up-to-date list of core team members can be found in MAINTAINERS.md. At this time, the project is still building the core team and defining roles and responsibilities. We are eagerly seeking individuals who would like to join the community and help us define and fill these roles.

• Assumptions
• Repository structure
• Development
• Deploy
• Resources

Accessibility, unit testing, and translation are being built in from the ground up. We want to make sound decisions that allow this app to scale, but understand that we also want to make a few decisions as possible at this early stage. We are still learning about this problem space, but we are sure that accessibility, testing, and translation are important.

This application uses NextJS's default file structure. You can learn more about this from NextJS.

Architecture design records are in this directory.

Next has a style where routing is determined by file structure. You'll find all of the application files inside of the app directory.

• [locale]: where the pages live
• api: looks like api endpoints with some automagic nextjs things
  • POST /export
  • GET /sitemap
• components: reused components in the application
• i18n: translation keys

features contains our redux stores, which is our data structure in this local-storage-focused app. You'll notice below that there's a question about Store default values and other data structure thoughts below in our notes and decisions but for now this is where we're keeping our data structures. As things become more complicated we will want to revisit our decisions in this area.

Where any public assets are stored.

Tooling and scripts to make the repository run smoothly and correctly.

This project follows trunk-based development, which means:

• Make small changes in short-lived feature branches and merge to main frequently.
• Be open to submitting multiple small pull requests for a single ticket (i.e. reference the same ticket across multiple pull requests).
• Treat each change you merge to main as immediately deployable to production. Do not merge changes that depend on subsequent changes you plan to make, even if you plan to make those changes shortly.
• Ticket any unfinished or partially finished work.
• Tests should be written for changes introduced, and adhere to the text percentage threshold determined by the project.

This project uses continuous deployment using Github Actions which is configured in the ./github/worfklows directory.

Pull-requests are merged to main.

1. Install node.js. For example, installing version 20 using brew:

   brew install node@20

2. Clone this repo to your local workspace. For example, using github cli:

   gh repo clone DSACMS/iv-verify

1. Change into the repo's directory.

   cd iv-verify

2. Install dependencies.

   npm install

3. Run the development server.

   npm run dev

4. Open http://localhost:3000/ with your browser to access the application.

1. Install docker.
2. Clone this repo to your local workspace. For example, using github cli:

   gh repo clone DSACMS/iv-verify

1. Change into the repo's directory.

   cd iv-verify

2. Do a clean install of the project.

   npm ci

3. Build the project.

   npm run build

4. Build the image. For example, with no stated tag:

   docker build -t iv-verify .

1. With an image built from above, start the image. The command below maps the external port to 3000.

   docker run -p 3000:3000 iv-verify

2. Open http://localhost:3000/ with your browser to access the application.

The Dockerfile contains logic checking to determine whether or not the server building the image uses ARM64 architecture. This is done because ARM64 does not include the Chromium open-source browser and Chromium is a dependency for some testing libraries used by the application. Without Chromium, the npm install step fails when building the image. As a result, the Dockerfile sets the PUPPETEER_SKIP_CHROMIUM_DOWNLOAD environment variable to false if the server machine is ARM64. This will result in Chromium be downloaded during the npm install which will allow the image build to proceed successfully. For additional references, see puppeteer/puppeteer#7740.

To run tests:

npm run test

To check the test coverage:

npm run coverage

This application uses the linter in NextJS and is executed as part of the pull request checks and you cannot merge without all checks passing. To run the linter locally:

npm run lint

This section refers to deploying to a cloud.gov sandbox environment.

The following steps only need to be done once per person. Once you have set up your sandbox environment, you will be able to deploy the application to it and access it publically.

Before being able to deploy into cloud.gov, you will need to sign up for a sandbox account on the platform. Only federal employees and contractors with a qualified US federal government email may obtain free sandbox space. To register, go to the sign up page. You will need access to your email and an authenticator app (such as Google Authenticator, 1password, Microsoft Authenticator, or Authy).

Refer to the Getting Started - Setting up the command line documentation on cloud.gov. The instructions will step through how to set up the Cloud Foundry command line interface and authenticate to your cloud.gov instance.

Here is how to migrate from one deployment namespace to another. We'll need to run a manual deployment to set up the namespace before setting up the gh action to reflect the new location.

1. In the new owner's repo, npm i && npm run build if you haven't already
2. Edit the manifest.yml to create the name you want. I've been using verify-ledger-prototype
3. cf push [name-in-manifest]

Reference: https://cloud.gov/docs/services/cloud-gov-service-account/#how-to-create-an-instance

To create a service account to use for deployments, first create a service instance associated with your

cf create-service cloud-gov-service-account space-deployer [name-in-manifest]

# For example:
cf create-service cloud-gov-service-account space-deployer verify-ledger-prototype

Next, create a service account and bind it to your service instance.

cf create-service-key [name-in-manifest] [your-key-name]

# For example:
cf create-service-key verify-ledger-prototype ledger-service-key

Generate the service key for the account.

cf service-key [name-in-manifest] [your-key-name]
 
# For example:
cf service-key verify-ledger-prototype ledger-service-key

The command will output a username and password that you will use for deploying the application. You will be prompted for your credentials when using the sandbox deployment workflow.

{
    "credentials": {
        "password": "oYasdfliaweinasfdliecVfake/",
        "username": "fakebeed-aabb-1234-feha0987654321000"
    }
}

The repository has a workflow for building and deploying the application to a cloud.gov sandbox.

1. Go to https://github.com/DSACMS/iv-verify/actions/workflows/deploy-to-sandbox.yml.

2. Click "Run Workflow" button on the right.

3. Fill out the following three fields:

   Field	Required	Description
   Cloud.gov service account username	Yes	The user name of service account of the sandbox owner's space.
   Cloud.gov service account password	Yes	The password of service account of the sandbox owner's space.
   Application name	No	The name of the application as it is defined in the owner's sandbox space. If no value is given, then the value in the manifest.yml is used.

4. Click the "Run Workflow" button in the dialog to start the processing.

• Set secrets for gh actions
• space-deployer docs

• JIRA
• Designs

• NextJS docs

Thank you for considering contributing to an Open Source project of the US Government! For more information about our contribution guidelines, see CONTRIBUTING.md.

The contents of this repository are managed by the US Digital Service. Those responsible for the code and documentation in this repository can be found in CODEOWNERS.md.

The iv-verify team is taking a community-first and open source approach to the product development of this tool. We believe government software should be made in the open and be built and licensed such that anyone can download the code, run it themselves without paying money to third parties or using proprietary software, and use it as they will.

We know that we can learn from a wide variety of communities, including those who will use or will be impacted by the tool, who are experts in technology, or who have experience with similar technologies deployed in other spaces. We are dedicated to creating forums for continuous conversation and feedback to help shape the design and development of the tool.

We also recognize capacity building as a key part of involving a diverse open source community. We are doing our best to use accessible language, provide technical and process documents, and offer support to community members with a wide variety of backgrounds and skillsets.

Principles and guidelines for participating in our open source community are can be found in COMMUNITY_GUIDELINES.md. Please read them before joining or starting a conversation in this repo or one of the channels listed below. All community members and participants are expected to adhere to the community guidelines and code of conduct when participating in community spaces including: code repositories, communication channels and venues, and events.

Information about how the iv-verify community is governed may be found in GOVERNANCE.md.

If you have ideas for how we can improve or add to our capacity building efforts and methods for welcoming people into our community, please let us know at iv-verify@cms.hhs.gov. If you would like to comment on the tool itself, please let us know by filing an issue on our GitHub repository.

Information about terminology and acronyms used in this documentation may be found in GLOSSARY.md.

We adhere to the CMS Open Source Policy. If you have any questions, just shoot us an email.

Submit a vulnerability: Unfortunately, we cannot accept secure submissions via email or via GitHub Issues. Please use our website to submit vulnerabilities at https://hhs.responsibledisclosure.com. HHS maintains an acknowledgements page to recognize your efforts on behalf of the American public, but you are also welcome to submit anonymously.

For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see SECURITY.md.

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication as indicated in LICENSE.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest.