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.
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 liveapi: looks like api endpoints with some automagic nextjs thingsPOST /exportGET /sitemap
components: reused components in the applicationi18n: 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.
- Install node.js. For example, installing version 20 using brew:
brew install node@20
- Clone this repo to your local workspace. For example, using github cli:
gh repo clone DSACMS/iv-verify
- Change into the repo's directory.
cd iv-verify - Install dependencies.
npm install
- Run the development server.
npm run dev
- Open http://localhost:3000/ with your browser to access the application.
- Install docker.
- Clone this repo to your local workspace. For example, using github cli:
gh repo clone DSACMS/iv-verify
- Change into the repo's directory.
cd iv-verify - Do a clean install of the project.
npm ci
- Build the project.
npm run build
- Build the image. For example, with no stated tag:
docker build -t iv-verify .
- 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
- 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 test coverage
npm run coverageThis application uses NextJS's built in linter. It's run as part of pull request checks and you cannot merge without all checks passing.
To run the linter locally, use npm run lint.
This project follows trunk-based development, which means:
- Make small changes in short-lived feature branches and merge to
mainfrequently. - 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
mainas 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.
- Go to https://github.com/DSACMS/iv-verify/actions/workflows/deploy.yml
- Click "Run Workflow" button on the right
- Click "Run Workflow" in the dialog that appears
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.
- In the new owner's repo,
npm i && npm run buildif you haven't already - Edit the
manifest.ymlto create the name you want. I've been usingverify-ledger-prototype cf push [name-in-manifest]
On successful deployment, you can set up the gh actions deployment
cf create-service cloud-gov-service-account space-deployer [name-in-manifest]cf create-service-key [name-in-manifest] [your-key-name]cf service-key [name-in-manifest] [your-key-name]- A username and password will be printed in your terminal. Using these, proceed to the next steps:
gh secret set CLOUD_GOV_DEPLOY_USERNAMEand enter this secret when promptedgh secret set CLOUD_GOV_DEPLOY_PASSWORDand enter this secret when prompted- From here, test out a deployment in the repo to test it out
- JIRA
- Designs
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 [email protected]. 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.