Documentation cleanup and updates (#469)

* Clean up architecture documentation * Remove old stuff from ADRs and READMEs, update for clarity * Fix typos * Color change for readability
GSA-TTS · Jan 31, 2025 · 08cef3c · 08cef3c
1 parent b2bfed0
commit 08cef3c
Show file tree

Hide file tree

Showing 37 changed files with 124 additions and 92 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/README.md b/README.md
@@ -4,24 +4,24 @@ Test bed for 10x forms tooling, completed as part of the [10x Forms Platform](ht
 
 ## Overview
 
-A C4-like architectural diagram is [available here](documents/diagram.md).
+An architectural overview is [available here](documents/architecture.md).
 
 Additional documentation:
 
 - [Architectural Decision Records (ADRs)](./documents/adr/)
 - [Release process](./documents/release-process.md)
 
-## Overview
-
-The platform is made up of the following high-level terms.
-
 ### Key personas
 
+The platform is targeted to the following user groups:
+
 - Form Builders: government program office staff or UX experts who create and publish "guided interview" web experiences for members of the public and fellow government staff via a friendly browser-based app, no coding necessary. For examples of "guided interview" style web experiences, check out [IRS Direct File](https://coforma.io/case-studies/irs-direct-file#results) (filing your taxes), [GetCalFresh](https://codeforamerica.org/news/overcoming-barriers-setting-expectations-for-calfresh-eligibility/) (Applying for food benefits) and [Court Forms Online](https://courtformsonline.org/) (filing court documents).
 - Form Fillers: folks who provide info to the government via guided interviews created by Form Builders
 
 ### Things
 
+Key concepts in the platform
+
 - **Blueprint**: produced by a form builder, the blueprint defines the structure of an interactive session between a government office and a form filler.
 - **Conversation**: one instance of a blueprint; the interactive session between a government office and a form filler. Other terms for this concept include dialogue or session.
 - **Pattern/template**: the building blocks of a blueprint, patterns implement UX best-practices, defining the content and behavior of the user interface.
@@ -62,10 +62,9 @@ If you start having unexplained build errors, the following commands are useful
 pnpm clean:dist # removes previously built files recursively
 pnpm clean:modules # removes node_module directories recursively
 
-# ... run more commands like pnpm install and pnpm build after you have run these 
+# ... run more commands like pnpm install and pnpm build after you have run these
 ```
 
-
 To start developing with hot reloading, use:
 
 ```bash

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. Currently, this application includes a client-side version of the form manager interface.
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
@@ -0,0 +1,60 @@
+# Forms Platform architecture
+
+## Overview
+
+Forms Platform is organized into several packages:
+
+| Package                        | Description                        | Dependencies                                                                                                                             |
+| ------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| [Forms](forms/README.md)       | Platform services and domain logic | [Common](common/README.md), [Database](database/README.md)                                                                               |
+| [Server](server/README.md)     | Platform Node.js web server        | [Auth](auth/README.md), [Common](common/README.md), [Database](database/README.md), [Design](design/README.md), [Forms](forms/README.md) |
+| [Design](design/README.md)     | User-facing interface components   | [Common](common/README.md), [Forms](forms/README.md)                                                                                     |
+| [Auth](auth/README.md)         | Authentication and authorization   | [Common](common/README.md), [Database](database/README.md)                                                                               |
+| [Common](common/README.md)     | Shared utilities                   | _None_                                                                                                                                   |
+| [Database](database/README.md) | Backend storage                    | [Common](common/README.md)                                                                                                               |
+
+## High-level architecture diagram
+
+This C4-like architectural diagram documents data flows in a typical deployment scenario:
+
+```mermaid
+flowchart TB
+    %% Style definitions
+    classDef blue fill:#2374ab,color:#fff
+    classDef invisible opacity:0
+
+    subgraph "External Users"
+        formFiller[Form Filler: Submits forms]
+        formCreator[Form Creator: Uses no-code interface to create forms]
+        formReviewer[Form Reviewer: Reviews submitted forms]
+    end
+
+    subgraph platform["Forms Platform (Internal)"]
+        style platform fill:#fcf8d4,color:#000
+        webServer[Platform Server: Handles form creation, submission, and interactions]:::blue
+        database[(Postgres DB: Stores form data and user information)]
+    end
+
+    subgraph "External Systems"
+        loginGov[Login.gov: Handles authentication]
+
+        subgraph "Agency Systems"
+            agencyBackend[Agency Backend Systems: Receives submitted form data]
+            s3Bucket[Amazon S3: Stores completed forms]
+        end
+    end
+
+    formCreator -->|Creates forms using| webServer
+    formFiller -->|Submits forms via| webServer
+    formReviewer -->|Reviews submitted forms using| webServer
+    webServer -->|Stores and retrieves form data from| database
+
+    webServer -->|Authenticates form creators - https| loginGov
+    webServer -->|Submits form data to Agency Backend - https| agencyBackend
+    webServer -->|Uploads form PDFs to S3 Bucket - https| s3Bucket
+
+    %% Forcing "External Systems" to be below "Forms Platform"
+    dummyNode[ ]:::invisible
+    webServer --> dummyNode
+    dummyNode --> loginGov
+```
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.