{"id":18793077,"url":"https://github.com/dsacms/iv-verify","last_synced_at":"2025-09-07T16:47:07.342Z","repository":{"id":255669673,"uuid":"808357732","full_name":"DSACMS/iv-verify","owner":"DSACMS","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-13T03:25:41.000Z","size":12841,"stargazers_count":5,"open_issues_count":14,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-25T20:47:38.737Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DSACMS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS.md","security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-30T22:51:47.000Z","updated_at":"2025-02-11T16:29:04.000Z","dependencies_parsed_at":"2024-12-20T02:41:30.218Z","dependency_job_id":"645112ff-16c8-4423-870b-03db49f5ffd8","html_url":"https://github.com/DSACMS/iv-verify","commit_stats":null,"previous_names":["dsacms/iv-verify"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DSACMS/iv-verify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-verify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-verify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-verify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-verify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DSACMS","download_url":"https://codeload.github.com/DSACMS/iv-verify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DSACMS%2Fiv-verify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274065598,"owners_count":25216443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T21:23:27.109Z","updated_at":"2025-09-07T16:47:07.313Z","avatar_url":"https://github.com/DSACMS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Income Verfication as a Service - Digital Ledger Intervention\n\n## About the Project\nIncome Verification as a Service (IVaaS) is a platform to aid in verifying income across means based benefit programs. It comprises multiple interventions to meet the needs of different income earner types. Background and context on the project can be found here\n\nThis repo is specific to the Digital Ledger intervention. The digital ledger is in the proof-of-concept stage. It is a mobile-first self guided applicaiton to be used by individuals who are self-employed to aid in creating business income and expenses ledgers, to be used for income verification. \n\nThis application is uses:\n* NextJS\n* React\n* USWDS react components\n* Deployment to cloud.gov\n\n## Core Team\nAn up-to-date list of core team members can be found in [MAINTAINERS.md](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.\n\n## Documentation index\n- [Assumptions](#assumptions)\n- [Repository structure](#repository-structure)\n- [Development](#development)\n- [Deploy](#deploy)\n- [Resources](#resources)\n\n## Assumptions\nAccessibility, 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.\n\n## Repository structure\nThis application uses NextJS's default file structure. You can learn more about this from [NextJS](https://nextjs.org/docs/getting-started/project-structure). \n\n### `adr`\nArchitecture design records are in this directory.\n\n### `app`\nNext has a style where routing is determined by file structure. You'll find all of the application files inside of the `app` directory.\n* `[locale]`: where the pages live\n* `api`: looks like api endpoints with some automagic nextjs things\n\t- `POST /export`\n\t- `GET /sitemap`\n* `components`: reused components in the application\n* `i18n`: translation keys\n\n### `lib`\n`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.\n\n### `public`\nWhere any public assets are stored.\n\n### `scripts`\nTooling and scripts to make the repository run smoothly and correctly.\n\n\n## Branching model\nThis project follows [trunk-based development](https://trunkbaseddevelopment.com/), which means:\n\n* Make small changes in [short-lived feature branches](https://trunkbaseddevelopment.com/short-lived-feature-branches/) and merge to `main` frequently.\n* Be open to submitting multiple small pull requests for a single ticket (i.e. reference the same ticket across multiple pull requests).\n* 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.\n* Ticket any unfinished or partially finished work.\n* Tests should be written for changes introduced, and adhere to the text percentage threshold determined by the project.\n\nThis project uses **continuous deployment** using [Github Actions](https://github.com/features/actions) which is configured in the [./github/worfklows](.github/workflows) directory.\n\nPull-requests are merged to `main`.\n\n## Development\n\n### Starting the application locally\n##### Prerequisite steps\n1. Install [node.js](https://nodejs.org/en/download/package-manager). For example, installing version 20 using brew:\n    ```bash\n    brew install node@20\n    ```\n1. Clone this repo to your local workspace. For example, using github cli:\n    ```bash\n    gh repo clone DSACMS/iv-verify\n    ```\n    \n##### Steps\n1. Change into the repo's directory.\n    ```bash\n    cd iv-verify\n    ```\n1. Install dependencies.\n    ```bash\n    npm install\n    ```\n1. Run the development server.\n    ```bash\n    npm run dev\n    ```\n1. Open [http://localhost:3000/](http://localhost:3000/) with your browser to access the application.\n\n### Running the application in a docker container\n\n##### Prerequisite steps\n1. Install [docker](https://www.docker.com/get-started/). \n1. Clone this repo to your local workspace. For example, using github cli:\n    ```bash\n    gh repo clone DSACMS/iv-verify\n    ```\n##### Steps to build the image\n1. Change into the repo's directory.\n    ```bash\n    cd iv-verify\n    ```\n1. Do a clean install of the project.\n    ```bash\n    npm ci\n    ```\n1. Build the project.\n    ```bash\n    npm run build\n    ```\n1. Build the image. For example, with no stated tag:\n    ```bash\n    docker build -t iv-verify .\n    ```\n##### Steps to start the image\n1. With an image built from above, start the image. The command below maps the external port to 3000.\n    ```bash\n    docker run -p 3000:3000 iv-verify\n    ``` \n1. Open [http://localhost:3000/](http://localhost:3000/) with your browser to access the application.\n\n##### Chromium architecture check in the Dockerfile\nThe [Dockerfile](./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. \nAs 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 https://github.com/puppeteer/puppeteer/issues/7740.\n\n## Tests and linting\n\nTo run tests:\n```bash\nnpm run test\n```\n\nTo check the test coverage:\n```bash\nnpm run coverage\n```\n\nThis application uses the linter in NextJS and is executed as part of the pull request checks and you cannot merge without all checks passing. \nTo run the linter locally:\n```bash\nnpm run lint\n```\n\n## Deploy\n\nThis section refers to deploying to a cloud.gov sandbox environment.\n\n### Set up your cloud.gov sandbox environment\nThe 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.\n\n#### Sign up for an account\nBefore 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](https://account.fr.cloud.gov/signup). You will need access to your email and an authenticator app (such as Google Authenticator, 1password, Microsoft Authenticator, or Authy).\n\n#### Download the Cloud Foundry CLI\n\nRefer to the [Getting Started - Setting up the command line](https://cloud.gov/docs/getting-started/setup/#set-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.\n\n#### Establish the application in your sandbox\nHere 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. \n\n1. In the new owner's repo, `npm i \u0026\u0026 npm run build` if you haven't already\n2. Edit the `manifest.yml` to create the name you want. I've been using `verify-ledger-prototype`\n2. `cf push [name-in-manifest]`\n\nReference: https://cloud.gov/docs/services/cloud-gov-service-account/#how-to-create-an-instance\n\n#### Create a service account for your deployments\n\nTo create a service account to use for deployments, first create a service instance associated with your \n   ```bash\n   cf create-service cloud-gov-service-account space-deployer [name-in-manifest]\n\n   # For example:\n   cf create-service cloud-gov-service-account space-deployer verify-ledger-prototype\n   ```\n\nNext, create a service account and bind it to your service instance.\n   ```bash\n   cf create-service-key [name-in-manifest] [your-key-name]\n   \n   # For example:\n   cf create-service-key verify-ledger-prototype ledger-service-key\n   ```\n\nGenerate the service key for the account.\n   ```bash\n   cf service-key [name-in-manifest] [your-key-name]\n    \n   # For example:\n   cf service-key verify-ledger-prototype ledger-service-key\n   ```\n\nThe 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.\n\n    {\n        \"credentials\": {\n            \"password\": \"oYasdfliaweinasfdliecVfake/\",\n            \"username\": \"fakebeed-aabb-1234-feha0987654321000\"\n        }\n    }\n\n### Deploy to the cloud.gov sandbox environment\nThe repository has a workflow for building and deploying the application to a cloud.gov sandbox.\n\n1. Go to https://github.com/DSACMS/iv-verify/actions/workflows/deploy-to-sandbox.yml.\n1. Click \"Run Workflow\" button on the right.\n1. Fill out the following three fields:\n\n    | Field | Required | Description |\n    | --- | --- | --- |\n    | Cloud.gov service account username  | Yes | The user name of service account of the sandbox owner's space. |\n    | Cloud.gov service account password | Yes | The password of service account of the sandbox owner's space. |\n    | 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. |\n1. Click the \"Run Workflow\" button in the dialog to start the processing.\n\n\n#### Deployment resources\n- [Set secrets for gh actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-environment)\n- [`space-deployer` docs](https://cloud.gov/docs/services/cloud-gov-service-account/)\n\n## Resources\n### Project-specific\n* JIRA\n* Designs\n\n### Technical\n* [NextJS docs](https://nextjs.org/docs)\n\n## Contributing\n\nThank you for considering contributing to an Open Source project of the US Government! For more information about our contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Codeowners\n\nThe 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](CODEOWNERS.md).\n\n## Community\n\nThe 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.\n\nWe 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.\n\nWe 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. \n\n### Community Guidelines\n\nPrinciples and guidelines for participating in our open source community are can be found in [COMMUNITY_GUIDELINES.md](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. \n\n## Governance\n\u003c!-- TODO: Make a short statement about how the project is governed (formally, or informally) and link to the GOVERNANCE.md file.--\u003e\n\nInformation about how the iv-verify community is governed may be found in [GOVERNANCE.md](GOVERNANCE.md).\n\n## Feedback\n\nIf 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.**\n\n## Glossary\n\nInformation about terminology and acronyms used in this documentation may be found in [GLOSSARY.md](GLOSSARY.md).\n\n## Policies\n\n### Open Source Policy\n\nWe adhere to the [CMS Open Source\nPolicy](https://github.com/CMSGov/cms-open-source-policy). If you have any\nquestions, just [shoot us an email](mailto:opensource@cms.hhs.gov).\n\n### Security and Responsible Disclosure Policy\n\n*Submit a vulnerability:* Unfortunately, we cannot accept secure submissions via\nemail or via GitHub Issues. Please use our website to submit vulnerabilities at\n[https://hhs.responsibledisclosure.com](https://hhs.responsibledisclosure.com).\nHHS maintains an acknowledgements page to recognize your efforts on behalf of\nthe American public, but you are also welcome to submit anonymously.\n\nFor more information about our Security, Vulnerability, and Responsible Disclosure Policies, see [SECURITY.md](SECURITY.md).\n\n## Public domain\n\nThis 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](https://creativecommons.org/publicdomain/zero/1.0/) as indicated in [LICENSE](LICENSE).\n\nAll 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsacms%2Fiv-verify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdsacms%2Fiv-verify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdsacms%2Fiv-verify/lists"}