CMS Blue Button API Static Site

Project Description

A static site for the Blue Button API website: https://bluebutton.cms.gov.

About the Project

The Blue Button API provides Medicare enrollee claims data to applications using the OAuth2.0 authorization flow. We aim to provide a developer-friendly, standards-based API that enables people with Medicare to connect their claims data to the applications, services, and research programs they trust.

Core Team

A list of core team members responsible for the code and documentation in this repository can be found in COMMUNITY.md.

Repository Structure

This structure documents the file structure necessary for static website, specifically.

├── .github/
├── .vscode/
├── ops/
├── public/
|   ├── img/
|   └── ...
├── scripts/
├── src/
│   ├── assets/
│   ├── components/
│   ├── content/
│   ├── layouts/
│   ├── pages/
│   ├── utils/
│   └── content.config.ts
├── .cspell.json
├── .gitignore
├── astro.config.mjs
├── eslint.config.mjs
├── package-lock.json
├── package.json
└── tsconfig.json

Development and Software Delivery Lifecycle

The following guide is for members of the project team who have access to the repository as well as code contributors. The main difference between internal and external contributions is that external contributors will need to fork the project and will not be able to merge their own pull requests. For more information on contributing, see: CONTRIBUTING.md.

Local Development

This project requires you to use Node.js. Once installed, you'll be able to run npm commands in your terminal.

Setup

1. Run npm install to install required dependencies
   • If this is your first time setting up the repo, run npx gulp copyAssets (yes, npx). This will copy assets from USWDS's node_modules directory into the correct project directory.
2. Then, run npm run dev to start you local development server.
3. Once you're ready to test a build, run npm run build. If this process fails, there are errors you'll need to resolve before you'll be able to deploy.

Additional Scripts

• Use npm run sync to update Astro's internal content processing and content types.
• Use npm run lint to check code quality against the defined eslint config.
• Use npm run typecheck to check for Typescript errors.
• Use npm run lint:linkcheck to verify validity of internal links the locally built site.
• Use npm run spellcheck to run cspell against the local content files.

Directories

./ops

This is where our files related to deploying the site live.

./scripts

Any reusable scripts we use for development will use this directory. Typically, these scripts will be referenced in a defined npm script, inside package.json.

./public

This is where static, uncompiled files are stored. Things like the site's meta image, resources like PDF's and text documents, and any other files that are served "as-is".

./public/img

This is the default directory where USWDS's CSS expects icons to be. We only reference a few, so they're manually added into this location rather than running USWDS's gulp scripts.

./src

This is where the bulk of the project lives. Everything in here is bundled into the project files

./src/assets

Assets that are used by and bundled into the site. These files are optimized and compiled at "build time".

./src/components

Reusable pieces of code that are referenced regularly throughout the site. Can be .astro or .tsx components.

./src/content

Where our site's content lives. This can be (mostly) any data type: markdown, json, csv, etc. It's reference and loaded into our site as defined in ./src/content.config.ts.

./src/layouts

Similar to ./src/components in that it's a reusable piece of code. Except these components are used to "wrap around" rather than "injected into".

./src/pages

This is where Astro looks to create all the pages on the site. Pages can be .astro or markdown files. In our case, we're using .astro and pulling in markdown content manually. Each page is exposed as a route based on its file name.

• ./src/pages/blog.astro creates a /blog route.
• ./src/pages/blog/[slug] creates a dynamic /blog/blog-slug route.
• ./src/pages/blog/[...slug] creates a dynamic /blog/a/b/c route.

More details on Astro routing

./src/utils

Various reusable functions that we use throught the site.

./src/content.config.ts

Where we define the site's content schemas. This let's us know the "shape" of our various content as we're working with it in our templates and components.

File Types

This project uses various file and content types, most importantly markdown, .astro, and .tsx

markdown

This site uses both .md and .mdx to render content. .mdx is a special type of markdown that is compiled with JavaScript. This means we can do some fancy things with it like use HTML directly, embed components, and reference frontmatter within a document.

More about MDX

.astro

Astro files are written with JSX, a special type of markup similar to HTML. You can use any type of valid HTML in these files. You can also write JavaScript functions and reference components.

The "frontmatter" is where the any variables are defined. These files are statically generated at build time so they cannot be used to run as client-side JavaScript (unless its written in a <script> tag).

Codebook, Resources, FHIR Responses, and Data Dictionary

Like all other content, these resources live in ./src/content under a path that matches the pattern of the live URL path. For example, https://bluebutton.cms.gov/resources/codesystem/eob-type/ content can be found at ./src/content/resources/codesystem/eob-type.

Any resource that is defined as .mdx or .json will automatically be processed just like any other content. However, other "data" content lives as .csv or .xml which require custom loaders. These loaders can be found in ./src/utils/loaders. These types of files undergo multiple steps of processing:

1. Data is ingested and initially parsed with a Zod schema. This turns ambiguous data files into strongly typed data which ensures consistency and prevents unexpected bugs.
   1. We typically return the processed data with a more terse schema that is easier consume in our page templates.
2. These files are processed again for Astro's specific content schema generation. You can see this defined in ./src/content.config.ts.

Deployment

For information about deploying to the static site, please referernce the following document in confluence: HOW-TO Static Site Updates.

Branching Model

This project follows standard GitHub flow practices:

• Make changes in feature branches and merge to master frequently
• Pull-requests are reviewed before merging
• Tests should be written for changes introduced
• Each change should be deployable to production

Make changes on a new branch and create pull requests to merge them into the master branch when ready.

When creating a new branch, use the naming convention [your-github-username]/[jira-ticket-number]-[description]. For example, mrengy/BB2-1511-layout-narrow-browser.

You'll need to use a Github Personal Access Token instead of a password in order to push changes.

Contributing

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

Community

The Blue Button Web Server 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.

Community Guidelines

Principles and guidelines for participating in our open source community are can be found in COMMUNITY.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.

Governance

For more information about our governance, see GOVERNANCE.md.

Feedback

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.

Policies

Open Source Policy

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

Security and Responsible Disclosure Policy

Submit a vulnerability: Vulnerability reports can be submitted through Bugcrowd. Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days.

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

Software Bill of Materials (SBOM)

A Software Bill of Materials (SBOM) is a formal record containing the details and supply chain relationships of various components used in building software.

In the spirit of Executive Order 14028 - Improving the Nation's Cyber Security, a SBOM for this repository is provided here: https://github.com/CMSGov/bluebutton-web-server/network/dependencies.

For more information and resources about SBOMs, visit: https://www.cisa.gov/sbom.

Public Domain

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.