Clean up architecture documentation

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 if 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,9 +62,8 @@ 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:
 

documents/architecture.md

@@ -0,0 +1,60 @@
+# Forms Platform architecture
+
+## Overview
+
+The 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
+    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
+```