Remove old stuff from ADRs and READMEs, update for clarity

GSA-TTS · Jan 29, 2025 · b0c074b · b0c074b
1 parent da868f9
commit b0c074b
Show file tree

Hide file tree

Showing 35 changed files with 59 additions and 47 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -18,7 +18,7 @@ RUN pnpm --filter=$APP_DIR --prod deploy /app/$APP_DIR
 FROM base AS app
 ARG APP_DIR
 
-LABEL org.opencontainers.image.description 10x Access to Justice Form Builder
+LABEL org.opencontainers.image.description 10x Forms Platform
 
 COPY --from=build /app/$APP_DIR /app/$APP_DIR
 COPY --from=build /usr/src/app/apps/$APP_DIR/dist /app/$APP_DIR/dist

diff --git a/apps/spotlight/README.md b/apps/spotlight/README.md
@@ -1,5 +1,5 @@
-# ATJ Spotlight - frontend interface
+# Forms Platform Spotlight - frontend interface
 
 ## Summary
 
-ATJ Spotlight is the public face of the 10x Access to Justice Platform project. We will share progress of our work and demo our findings here.
+Forms Platform Spotlight is the public face of the project. We will share progress of our work and demo our findings here.
diff --git a/apps/spotlight/src/layouts/Layout.astro b/apps/spotlight/src/layouts/Layout.astro
@@ -46,11 +46,12 @@ const context = getAppContext();
     <meta name="generator" content={Astro.generator} />
     <meta
       name="description"
-      content=`10x Access to Justice Spotlight - ${title}`
+      content=`10x Forms Platform Spotlight - ${title}`
     />
   </head>
   <body id="top">
-    <script is:inline defer src={`${context.uswdsRoot}js/uswds.min.js`}></script>
+    <script is:inline defer src={`${context.uswdsRoot}js/uswds.min.js`}
+    ></script>
     <div class="usa-app usa-app__theme-1">
       <UsaBanner />
       <Header />

diff --git a/apps/spotlight/src/pages/forms/index.astro b/apps/spotlight/src/pages/forms/index.astro
@@ -3,6 +3,6 @@ import { AppFormPage } from '../../features/form-page';
 import ContentLayout from '../../layouts/ContentLayout.astro';
 ---
 
-<ContentLayout title="10x Access to Justice Spotlight">
+<ContentLayout title="10x Forms Platform Spotlight">
   <AppFormPage client:only="react" />
 </ContentLayout>
diff --git a/apps/spotlight/src/pages/index.astro b/apps/spotlight/src/pages/index.astro
@@ -2,6 +2,7 @@
 import AppFormManager from '../components/AppFormManager';
 import Layout from '../layouts/Layout.astro';
 ---
-<Layout title="10x Access to Justice Spotlight">
+
+<Layout title="10x Forms Platform Spotlight">
   <AppFormManager client:only />
-</Layout>
+</Layout>
diff --git a/apps/spotlight/src/pages/manage/import-pdf.astro b/apps/spotlight/src/pages/manage/import-pdf.astro
@@ -2,6 +2,6 @@
 import ContentLayout from '../../layouts/ContentLayout.astro';
 ---
 
-<ContentLayout title="10x Access to Justice Spotlight">
+<ContentLayout title="10x Forms Platform Spotlight">
   <!--DocumentImporter client:only /-->
 </ContentLayout>
diff --git a/apps/spotlight/src/pages/manage/index.astro b/apps/spotlight/src/pages/manage/index.astro
@@ -3,6 +3,6 @@ import AppFormManager from '../../components/AppFormManager';
 import Layout from '../../layouts/Layout.astro';
 ---
 
-<Layout title="10x Access to Justice Spotlight">
+<Layout title="10x Forms Platform Spotlight">
   <AppFormManager client:only="react" />
 </Layout>
diff --git a/documents/adr/0002-generate-dependency-diagram.md b/documents/adr/0002-generate-dependency-diagram.md
@@ -4,11 +4,11 @@ Date: 2023-09-13
 
 ## Status
 
-Accepted
+Deprecated - replaced with manual documentation [available here](../architecture.md).
 
 ## Context
 
-The 10x Digital Access to Justice Platform project is kicking off, and we need to document our system and software architecture for both internal and external stakeholders.
+The Forms Platform project is kicking off, and we need to document our system and software architecture for both internal and external stakeholders.
 
 ## Decision
 

diff --git a/documents/adr/0005-build-system.md b/documents/adr/0005-build-system.md
@@ -8,7 +8,7 @@ Accepted
 
 ## Context
 
-The development phase of "10x Digital Access to Justice Platform" has started. The development effort will focus on building modular form system components.
+The development phase of Forms Platform has started. The development effort will focus on building modular form system components.
 
 A method of structuring cohesive and well-encapsulated modules is required. Additionally, the module system should enable efficient builds and integrate with other goals, such as [generating dependency diagrams](./0002-generate-dependency-diagram.md).
 

diff --git a/documents/adr/0006-spotlight-frontend.md b/documents/adr/0006-spotlight-frontend.md
@@ -8,7 +8,7 @@ Accepted
 
 ## Context
 
-The 10x Digital Access to Justice Platform project requires a public web presence to communicate project details and as a host for prototypes and demos.
+The Forms Platform project requires a public web presence to communicate project details and as a host for prototypes and demos.
 
 Additionally, the project team aspires to create modular components that are flexible and easy-to-leverage by software development teams throughout government. The project's web presence is a convenient place to dogfood any components that are built for wider consumption.
 

diff --git a/documents/adr/0007-initial-css-strategy.md b/documents/adr/0007-initial-css-strategy.md
@@ -8,7 +8,7 @@ Accepted
 
 ## Context
 
-The 10x Digital Access to Justice Platform project will produce many frontend components that leverage the [U.S. Web Design System](https://designsystem.digital.gov/).
+The Forms Platform project will produce many frontend components that leverage the [U.S. Web Design System](https://designsystem.digital.gov/).
 
 The project team desires a method of managing CSS using a method that maximizes utility outside this project.
 

diff --git a/documents/adr/0008-initial-form-handling-strategy.md b/documents/adr/0008-initial-form-handling-strategy.md
@@ -8,7 +8,7 @@ Accepted
 
 ## Context
 
-The 10x Digital Access to Justice Platform project will require a strategy of organizing form-handling logic and presentation.
+Forms Platform will require a strategy of organizing form-handling logic and presentation.
 
 We aim to deliver utilities to aid in the creation of accessible, user-friendly forms. These forms will be defined using a declarative format that may be integrated with tools like a no-code form builder and a UI component library.
 

diff --git a/documents/adr/0009-design-assets-workflow.md b/documents/adr/0009-design-assets-workflow.md
@@ -8,9 +8,9 @@ Accepted
 
 ## Context
 
-The 10x Digital Access to Justice Platform project will produce user interface components for form lifecycle operations including creating and filling web-based form. These components will be demo'd as part of the project's phase 3 work, and are intended to be leveraged by third-parties. These components inherit the stylesheet strategy outlined in ADR [./0007-initial-css-strategy.md](./0007-initial-css-strategy.md).
+Forms Platform requires user interface components for form lifecycle operations, including creating and filling web-based forms. These components will be demo'd as part of the project's phase 3 work, and are intended to be leveraged by third-parties. These components inherit the stylesheet strategy outlined in ADR [./0007-initial-css-strategy.md](./0007-initial-css-strategy.md).
 
-The project team desires a method of organizing frontend components in a manner that facilitates rapid development and collaboration use cases.
+The project team requires a method of organizing frontend components that facilitates rapid development and collaboration.
 
 ## Decision
 

diff --git a/documents/adr/0010-end-to-end-testing.md b/documents/adr/0010-end-to-end-testing.md
@@ -4,15 +4,20 @@ Date: 2024-07-08
 
 ## Status
 
-Pending
+Approved
 
 ## Context
 
-Certain tests are not able to be performed with Storybook and JSDOM (e.g. drag-and-drop). The ability to replicate more complex user interactions in the test suite through an actual browser can provide this feature.
+The Forms Platform team would like certainty that the platform codebase works end-to-end. This should include granular tests on a component level, and tests that cover multi-step user journeys.
+
+Certain frontend tests are not able to be performed with browser fakes, such as Storybook tests run via JSDOM (e.g. drag-and-drop). The ability to replicate more complex user interactions in the test suite through an actual browser can provide this feature.
 
 ## Decision
-The end-to-end tests should be used sparingly since they are slower to run than the ones through JSDOM. We will use Playwright in CI/CD for the comprehensive tests and JSDOM during development for speed. Storybook still should be the primary mechanism for UI testing, and during CI/CD, the interaction tests will be run in Playwright using a docker container against the build. 
+
+We will use Playwright for end-to-end testing. End-to-end tests should be used sparingly since they are the slowest tests. These comprehensive tests will be stored in the e2e directory, omitted from default dev test runners, and run automatically via CI/CD.
+
+Vitest Browser Mode will be used for interaction testing via Storybook as well as more traditional Vitest unit tests. Storybook will be the primary mechanism for UI testing, where appropriate.
 
 ## Consequences
 
-There are some tests that will be end-to-end that run against the built application, while the interaction tests will run against the built Storybook. The end-to-end tests will be in the e2e directory, and docker will be used to make the test environment consistent.
+The frontend will have strong test coverage by leveraging fast-running unit tests in a real browser, and multi-step user flows will be tested via Playwright end-to-end tests.
diff --git a/documents/adr/0011-secrets-management.md b/documents/adr/0011-secrets-management.md
@@ -8,7 +8,7 @@ Approved
 
 ## Context
 
-The Form Platform requires a method of managing secrets. During the early prototyping phase, we used Terraform with AWS Systems Manager Parameter Store. Secrets were manually created via the AWS console, and lookups were handled by Terraform's corresponding data provider.
+The Forms Platform requires a method of managing secrets. During the early prototyping phase, we used Terraform with AWS Systems Manager Parameter Store. Secrets were manually created via the AWS console, and lookups were handled by Terraform's corresponding data provider.
 
 As we look to operationalize management processes, tooling for working with secrets will become increasingly helpful. This has become apparent with our first scenario, the login.gov keypair, which needs to be unique for each deployed application.
 

diff --git a/documents/adr/0012-rich-text-editor.md b/documents/adr/0012-rich-text-editor.md
@@ -18,4 +18,4 @@ Quill was originally installed, but there was a known issue in being able to exe
 
 ## Consequences
 
-TipTap is a popular package that works outside the React ecosystem, so it is portable if there is ever a need to move to a different JS framework. The plugin does operate on a freemium model with the subset of features being free with additional, more advanced features having a cost. However, based on the features we use at the time of this ADR, the free features are robust enough to current requirements as well as the most likely requirements in the future. 
+TipTap is a popular package that works outside the React ecosystem, so it is portable if there is ever a need to move to a different JS framework. The plugin does operate on a freemium model with the subset of features being free with additional, more advanced features having a cost. However, based on the features we use at the time of this ADR, the free features are robust enough to current requirements as well as the most likely requirements in the future.
diff --git a/documents/adr/0013-database-strategy.md b/documents/adr/0013-database-strategy.md
@@ -8,7 +8,7 @@ Approved
 
 ## Context
 
-During the prototyping and demo phase, the Form Platform used browser-local storage in lieu of a database. This allowed the team to limit development efforts to a simple static site, avoiding the cost of building a backend system.
+During the prototyping and demo phase, Forms Platform used browser-local storage in lieu of a database. This allowed the team to limit development efforts to a simple static site, avoiding the cost of building a backend system.
 
 As we prepare to support our first government use case, we require a database to persist users, forms, form sessions, form submissions, and other future data.
 

diff --git a/documents/adr/0014-authentication.md b/documents/adr/0014-authentication.md
@@ -8,7 +8,7 @@ Approved
 
 ## Context
 
-The Form Platform requires a method of authenticating users. We are inclined to default to [Login.gov](https://login.gov/), a government-wide federated service hosted by [TTS](https://www.gsa.gov/about-us/organization/federal-acquisition-service/technology-transformation-services), unless circumstances prevent its usage.
+Forms Platform requires a method of authenticating users. We are inclined to default to [Login.gov](https://login.gov/), a government-wide federated service hosted by [TTS](https://www.gsa.gov/about-us/organization/federal-acquisition-service/technology-transformation-services), unless circumstances prevent its usage.
 
 When using Login.gov, we need to choose which library and other integration details we will leverage.
 
@@ -23,3 +23,5 @@ Lucia and Arctic will provide us will a solid workable solution, and provides us
 Lucia manages sessions, but in the future we may find it preferable to manage them ourselves.
 
 Additionally, Arctic does not support JWT-based auth. We may want to consider node-openid-client, or an alternative, for a simpler approach. This would require our own session management.
+
+This decision should be reevaluated once Forms Platform integrates with an identity provider other than login.gov.
diff --git a/documents/adr/0015-rest-api.md b/documents/adr/0015-rest-api.md
@@ -8,13 +8,13 @@ Approved
 
 ## Context
 
-During the prototyping and demo phase, the Form Platform used client-side services that persisted to browser local storage. As we introduce a backend to support agency users, we need to structure an API for the content authoring operations of the platform.
+During the prototyping and demo phase, Forms Platform used client-side services that persisted to browser local storage. As we introduce a backend to support agency users, we need to structure an API for the content authoring operations of the platform.
 
 ## Decision
 
-The Form Platform will initially implement an HTTP API in the Astro server. The API will aim to be an idiomatic REST API. A client-side service that proxies requests via HTTP calls will be injected into the form manager implementation.
+Forms Platform will initially implement an HTTP API in the Astro server. The API will aim to be an idiomatic REST API. A client-side service that proxies requests via HTTP calls will be injected into the form manager implementation.
 
-For the short term, we will maintain the existing client-side local storage service implementation. This will allow us to continue to test the form platform in static site mode, without a backend, as well as provide an implementation for in-browser integration testing. This will be reevaluated as we mature the form builder portion of the codebase.
+For the short term, we will maintain the existing client-side local storage service implementation. This will allow us to continue to test Forms Platform in static site mode, without a backend, as well as provide an implementation for in-browser integration testing. This will be reevaluated as we mature the form builder portion of the codebase.
 
 ## Consequences
 

diff --git a/documents/architecture.md b/documents/architecture.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Forms Platform is organized into several packages:
+Forms Platform is organized into several packages:
 
 | Package                        | Description                        | Dependencies                                                                                                                             |
 | ------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |

diff --git a/documents/doj-diagram.md b/documents/doj-diagram.md
@@ -1,6 +1,6 @@
 # Forms Platform - DOJ architecture diagram
 
-Sample diagram of a potential DOJ deployment of the Forms Platform.
+Sample diagram of a potential DOJ deployment of Forms Platform.
 
 ```mermaid
 flowchart TB

diff --git a/documents/release-process.md b/documents/release-process.md
@@ -7,7 +7,7 @@ There are currently two environments:
 
 ## Overview
 
-To promote continuous integration, the 10x Forms Platform uses trunk-based development. In trunk-based development, we collaborate in a single, mainline branch.
+To promote continuous integration, Forms Platform uses trunk-based development. In trunk-based development, we collaborate in a single, mainline branch.
 
 Deployments are managed by Terraform CDK. On merge to main, the [../.github/workflows/deploy.yml](../.github/workflows/deploy.yml) Github Action workflow builds Docker images for each app in the repository, pushes them to [ghcr.io](https://github.com/orgs/GSA-TTS/packages?repo_name=atj-platform), and deploys to the dev environment (`gsa-tts-10x-forms-dev`).
 

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "10x-forms",
   "version": "1.0.0",
-  "description": "Test bed for Access to Justice platform tooling.",
+  "description": "10x Forms Platform",
   "type": "module",
   "main": "index.js",
   "license": "CC0",

diff --git a/packages/database/README.md b/packages/database/README.md
@@ -1,6 +1,6 @@
 # @atj/database
 
-This package maintains the supporting infrastructure for the Form Platform's
+This package maintains the supporting infrastructure for the Forms Platform
 database.
 
 PostgreSQL is the supported production database. Sqlite3 is also supported,

diff --git a/packages/design/README.md b/packages/design/README.md
@@ -1,6 +1,6 @@
 # @atj/design
 
-This package encapsulates all the design components used in 10x Digital Access to Justice frontend applications.
+This package encapsulates all the design components used in Forms Platform frontend applications.
 
 This includes:
 

diff --git a/packages/forms/README.md b/packages/forms/README.md
@@ -1,8 +1,8 @@
 # @atj/forms
 
-This library includes all of the core business logic of the Forms Platform.
+This library includes all of the core business logic of Forms Platform.
 
-- [./src/services](./src/services): The public interface of the Forms Platform is implemented here
+- [./src/services](./src/services): The public interface of Forms Platform is implemented here
 - [./src/patterns](./src/patterns/README.md): Form building blocks, aka "patterns"
 - [./src/repository](./src/repository): Database routines
 - [./src/documents](./src/documents): Document ingest and creation

diff --git a/packages/forms/src/patterns/README.md b/packages/forms/src/patterns/README.md
@@ -1,6 +1,6 @@
 # Forms Platform - Patterns
 
-Patterns are the Forms Platform's primary building block, a reusable module that may be configured via the no-code form builder to craft custom user experiences.
+Patterns are the platform's primary building block, a reusable module that may be configured via the no-code form builder to craft custom user experiences.
 
 Patterns are stored on the form `Blueprint`'s pattern attribute.
 

diff --git a/packages/server/README.md b/packages/server/README.md
@@ -1,6 +1,6 @@
 # @atj/server
 
-The form platform's web server.
+The Forms Platform web server.
 
 ## Build
 

diff --git a/packages/server/src/components/Header.astro b/packages/server/src/components/Header.astro
@@ -30,7 +30,7 @@ const { session } = getUserSession(Astro);
     <div class="usa-navbar">
       <div class="usa-logo">
         <em class="usa-logo__text">
-          <a href={routes.getHomeUrl(baseUrl)} title="10x Access to Justice">
+          <a href={routes.getHomeUrl(baseUrl)} title="10x Forms Platform">
             <img src={logoSvg.src} role="img" alt="10x Logo" />
             <span class="text-white">{title}</span>
           </a>

diff --git a/packages/server/src/layouts/Layout.astro b/packages/server/src/layouts/Layout.astro
@@ -43,7 +43,7 @@ const { title } = Astro.props;
     <meta name="generator" content={Astro.generator} />
     <meta
       name="description"
-      content=`10x Access to Justice Spotlight - ${title}`
+      content=`10x Forms Platform Spotlight - ${title}`
     />
   </head>
   <body id="top">

diff --git a/packages/server/src/pages/forms/[id].astro b/packages/server/src/pages/forms/[id].astro
@@ -47,7 +47,10 @@ if (Astro.request.method === 'POST') {
     // They're later normalized into an array during response validation
     if (value instanceof File) {
       formDataObject[key] = value;
-    } else if (Array.isArray(value) && value.every(item => item instanceof File)) {
+    } else if (
+      Array.isArray(value) &&
+      value.every(item => item instanceof File)
+    ) {
       formDataObject[key] = value;
     } else {
       formDataObject[key] = value.toString();
@@ -115,6 +118,6 @@ setFormSessionCookie(sessionResult.data.id);
 const formSession = sessionResult.data.data;
 ---
 
-<ContentLayout title="10x Access to Justice">
+<ContentLayout title="10x Forms Platform">
   <AppForm client:load session={formSession} uswdsRoot={ctx.uswdsRoot} />
 </ContentLayout>
diff --git a/packages/server/src/pages/index.astro b/packages/server/src/pages/index.astro
@@ -6,6 +6,6 @@ import Layout from '../layouts/Layout.astro';
 const { baseUrl, uswdsRoot } = await getServerContext(Astro);
 ---
 
-<Layout title="10x Access to Justice">
+<Layout title="10x Forms Platform">
   <AppFormManager client:only="react" ctx={{ baseUrl, uswdsRoot }} />
 </Layout>
diff --git a/packages/server/src/pages/manage/import-pdf.astro b/packages/server/src/pages/manage/import-pdf.astro
@@ -2,6 +2,6 @@
 import ContentLayout from '../../layouts/ContentLayout.astro';
 ---
 
-<ContentLayout title="10x Access to Justice">
+<ContentLayout title="10x Forms Platform">
   <!--DocumentImporter client:only /-->
 </ContentLayout>
diff --git a/packages/server/src/pages/manage/index.astro b/packages/server/src/pages/manage/index.astro
@@ -6,6 +6,6 @@ import { getServerContext } from '../../config/astro.js';
 const ctx = await getServerContext(Astro);
 ---
 
-<Layout title="10x Access to Justice">
+<Layout title="10x Forms Platform">
   <AppFormManager client:only="react" ctx={ctx} />
 </Layout>
diff --git a/packages/server/src/pages/signout/index.astro b/packages/server/src/pages/signout/index.astro
@@ -7,7 +7,7 @@ const ctx = await getServerContext(Astro);
 const userSession = getUserSession(Astro);
 ---
 
-<Layout title="10x Access to Justice">
+<Layout title="10x Forms Platform">
   <div class="grid-container grid-row margin-top-4">
     <div class="tablet:grid-col-3 grid-col-4"></div>
     <div class="usa-card mobile:grid-col-12 tablet:grid-col-6 grid-col-4">
Original file line number	Diff line number	Diff line change
Expand Up		@@ -18,4 +18,4 @@ Quill was originally installed, but there was a known issue in being able to exe

		## Consequences

		TipTap is a popular package that works outside the React ecosystem, so it is portable if there is ever a need to move to a different JS framework. The plugin does operate on a freemium model with the subset of features being free with additional, more advanced features having a cost. However, based on the features we use at the time of this ADR, the free features are robust enough to current requirements as well as the most likely requirements in the future.
		TipTap is a popular package that works outside the React ecosystem, so it is portable if there is ever a need to move to a different JS framework. The plugin does operate on a freemium model with the subset of features being free with additional, more advanced features having a cost. However, based on the features we use at the time of this ADR, the free features are robust enough to current requirements as well as the most likely requirements in the future.