diff --git a/README.md b/README.md index aafd32369..fa801bc6e 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,6 @@ We also have: You can find our code in the following repositories: - [forms-admin](https://github.com/alphagov/forms-admin) - our application for building forms. -- [forms-api](https://github.com/alphagov/forms-api) - our application for storing and serving form definitions. - [forms-runner](https://github.com/alphagov/forms-runner) - our application for hosting forms, so that they can be filled in by members of the public. - [forms-e2e-tests](https://github.com/alphagov/forms-e2e-tests) - end-to-end tests for the service. - [forms-product-page](https://github.com/alphagov/forms-product-page) - our product pages, as seen at [https://forms.service.gov.uk](https://forms.service.gov.uk) diff --git a/diagrams/class-diagrams/README.md b/diagrams/class-diagrams/README.md index f1d33317c..5afa06408 100644 --- a/diagrams/class-diagrams/README.md +++ b/diagrams/class-diagrams/README.md @@ -24,7 +24,7 @@ generator="mermaid" rake erd This will create a file called `erd.mmd` in the root of the application. -## Update the diagram +## Update the diagram 1. Open the file in an editor and copy the contents (all of the `classDiagram` block). 2. Paste the contents into the corresponding diagram file, replacing everything inside the "mermaid" block: diff --git a/diagrams/class-diagrams/admin.md b/diagrams/class-diagrams/admin.md index ccef1694c..19c2d6324 100644 --- a/diagrams/class-diagrams/admin.md +++ b/diagrams/class-diagrams/admin.md @@ -33,6 +33,7 @@ classDiagram `Form` : +text declaration_text `Form` : +string external_id `Form` : +text form_slug + `Form` : +string language `Form` : +text name `Form` : +string payment_url `Form` : +text privacy_policy_url @@ -49,30 +50,28 @@ classDiagram `Form` : +text support_url `Form` : +text support_url_text `Form` : +text what_happens_next_markdown + class `FormDocument` + `FormDocument` : +jsonb content + `FormDocument` : +text tag class `FormSubmissionEmail` `FormSubmissionEmail` : +string confirmation_code `FormSubmissionEmail` : +string created_by_email `FormSubmissionEmail` : +string created_by_name - `FormSubmissionEmail` : +integer form_id `FormSubmissionEmail` : +string temporary_submission_email `FormSubmissionEmail` : +string updated_by_email `FormSubmissionEmail` : +string updated_by_name class `Group` - `Group` : +boolean branch_routing_enabled - `Group` : +boolean exit_pages_enabled `Group` : +text external_id `Group` : +string name `Group` : +string status `Group` : +boolean welsh_enabled class `GroupForm` - `GroupForm` : +integer form_id class `Membership` `Membership` : +string role class `MouSignature` class `Organisation` `Organisation` : +string abbreviation `Organisation` : +boolean closed - `Organisation` : +integer default_group_id `Organisation` : +string govuk_content_id `Organisation` : +boolean internal `Organisation` : +string name @@ -84,7 +83,6 @@ classDiagram `Page` : +text hint_text `Page` : +boolean is_optional `Page` : +boolean is_repeatable - `Page` : +integer next_page `Page` : +text page_heading `Page` : +integer position `Page` : +text question_text @@ -106,9 +104,11 @@ classDiagram `User` : +text permissions `User` : +string provider `User` : +boolean remotely_signed_out + `User` : +string research_contact_status `User` : +string role `User` : +datetime terms_agreed_at `User` : +string uid + `User` : +datetime user_research_opted_in_at `Item` --> `PaperTrail::Version` `Organisation` --> `PaperTrail::Version` `User` --> `PaperTrail::Version` @@ -123,7 +123,11 @@ classDiagram `Organisation` --> `MouSignature` `Group` --> `Membership` `Group` --> `GroupForm` + `Form` -- `GroupForm` + `Group` ..> `Form` + `Form` --> `FormDocument` `Form` --> `Page` + `Form` -- `FormSubmissionEmail` `Page` --> `Condition` `Condition` .. `Form` - ``` +``` diff --git a/diagrams/class-diagrams/api.md b/diagrams/class-diagrams/api.md deleted file mode 100644 index 5af79ddf7..000000000 --- a/diagrams/class-diagrams/api.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: GOV.UK Forms API class diagram ---- - -# GOV.UK Forms API class diagram -## 2025-05-29 - -```mermaid -classDiagram - direction RL - class `AccessToken` - `AccessToken` : +datetime deactivated_at - `AccessToken` : +string description - `AccessToken` : +datetime last_accessed_at - `AccessToken` : +string owner - `AccessToken` : +string token_digest - class `Api::V2::Form` - `Api::V2::Form` : +integer creator_id - `Api::V2::Form` : +boolean declaration_section_completed - `Api::V2::Form` : +text declaration_text - `Api::V2::Form` : +string external_id - `Api::V2::Form` : +text form_slug - `Api::V2::Form` : +text name - `Api::V2::Form` : +string payment_url - `Api::V2::Form` : +text privacy_policy_url - `Api::V2::Form` : +boolean question_section_completed - `Api::V2::Form` : +string s3_bucket_aws_account_id - `Api::V2::Form` : +string s3_bucket_name - `Api::V2::Form` : +string s3_bucket_region - `Api::V2::Form` : +boolean share_preview_completed - `Api::V2::Form` : +string state - `Api::V2::Form` : +text submission_email - `Api::V2::Form` : +string submission_type - `Api::V2::Form` : +text support_email - `Api::V2::Form` : +text support_phone - `Api::V2::Form` : +text support_url - `Api::V2::Form` : +text support_url_text - `Api::V2::Form` : +text what_happens_next_markdown - class `Api::V2::FormDocument` - `Api::V2::FormDocument` : +jsonb content - `Api::V2::FormDocument` : +text tag - class `Condition` - `Condition` : +string answer_value - `Condition` : +text exit_page_heading - `Condition` : +text exit_page_markdown - `Condition` : +boolean skip_to_end - class `Form` - `Form` : +integer creator_id - `Form` : +boolean declaration_section_completed - `Form` : +text declaration_text - `Form` : +string external_id - `Form` : +text form_slug - `Form` : +text name - `Form` : +string payment_url - `Form` : +text privacy_policy_url - `Form` : +boolean question_section_completed - `Form` : +string s3_bucket_aws_account_id - `Form` : +string s3_bucket_name - `Form` : +string s3_bucket_region - `Form` : +boolean share_preview_completed - `Form` : +string state - `Form` : +text submission_email - `Form` : +string submission_type - `Form` : +text support_email - `Form` : +text support_phone - `Form` : +text support_url - `Form` : +text support_url_text - `Form` : +text what_happens_next_markdown - class `MadeLiveForm` - `MadeLiveForm` : +json json_form_blob - class `Page` - `Page` : +jsonb answer_settings - `Page` : +text answer_type - `Page` : +text guidance_markdown - `Page` : +text hint_text - `Page` : +boolean is_optional - `Page` : +boolean is_repeatable - `Page` : +integer next_page - `Page` : +text page_heading - `Page` : +integer position - `Page` : +text question_text - class `PaperTrail::Version` - `PaperTrail::Version` : +string event - `PaperTrail::Version` : +string item_type - `PaperTrail::Version` : +jsonb object - `PaperTrail::Version` : +jsonb object_changes - `PaperTrail::Version` : +string whodunnit - `Item` --> `PaperTrail::Version` - `Condition` --> `PaperTrail::Version` - `Form` --> `PaperTrail::Version` - `Page` --> `PaperTrail::Version` - `Api::V2::Form` --> `Api::V2::FormDocument` - `Form` --> `Page` - `Page` --> `Condition` - `Form` --> `MadeLiveForm` - `Form` --> `Api::V2::FormDocument` - `Condition` .. `Form` -``` diff --git a/diagrams/sequence-diagrams/README.md b/diagrams/sequence-diagrams/README.md index 2ea582a22..c480c997b 100644 --- a/diagrams/sequence-diagrams/README.md +++ b/diagrams/sequence-diagrams/README.md @@ -2,7 +2,7 @@ ## Introduction -The diagrams in this folder (created using [Mermaid](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams)) show the interactions between users and GOV.UK Forms, including the 3 applications [forms-admin](https://github.com/alphagov/forms-admin), [forms-api](https://github.com/alphagov/forms-api), and [forms-runner](https://github.com/alphagov/forms-runner). +The diagrams in this folder (created using [Mermaid](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams)) show the interactions between users and GOV.UK Forms, including the two main applications [forms-admin](https://github.com/alphagov/forms-admin) and [forms-runner](https://github.com/alphagov/forms-runner). The diagram below is to provide an overview of the different users and systems that interact with each other. For clarity, not all interactions are shown. Please refer to individual sequence diagrams for detailed interactions. @@ -28,15 +28,14 @@ graph TD subgraph sg1 [GOV.UK Forms] admin(forms-admin) - api(forms-api) runner(forms-runner) end editor---runner - auth0 --- admin --- api + auth0 --- admin filler --- govuk - filler --- runner --- api + filler --- runner --- admin notify(GOV.UK Notify) diff --git a/diagrams/sequence-diagrams/changing-a-form.md b/diagrams/sequence-diagrams/changing-a-form.md index 1abd18e07..52e6aa4d0 100644 --- a/diagrams/sequence-diagrams/changing-a-form.md +++ b/diagrams/sequence-diagrams/changing-a-form.md @@ -8,48 +8,35 @@ sequenceDiagram participant browser as Web Browser participant admin as forms-admin link admin: GitHub repo @ https://github.com/alphagov/forms-admin - participant api as forms-api - link api: GitHub repo @ https://github.com/alphagov/forms-api note right of user: Form has already been made live user->>browser: visit live form page browser->>admin: GET /forms/{form id}/live - admin->>api: GET /api/v1/forms/{form id} - admin->>api: GET /api/v1/forms/{form id}/live browser-->>user: show live form page user->>browser: click "Create a draft to edit" button browser->>admin: GET /forms/{form id} - admin->>api: GET /forms/{form id} - admin->>api: GET /forms/{form id}/pages browser-->>user: show draft form page with task list - note over user,api: User edits the draft form (See Creating form)
until they are ready to make their changes live + note over user,admin: User edits the draft form (See Creating form)
until they are ready to make their changes live user->>browser: click "Make your changes live" task browser->>admin: GET /forms/{form id}/make-live - admin->>api: GET /api/v1/forms/{form id} browser-->>user: show "Make your changes live" page alt form creator decides not to make form live user->>browser: click "No" and submits page browser->>admin: POST /forms/{form id}/make-live
payload: {forms_make_live_form"=>
{"confirm_make_live"=>"not_made_live"},
"form_id"=>"{form id"}} - admin->>api: GET /api/v1/forms/{form id} admin-->>browser: REDIRECT 302 browser->>admin: GET /forms/{form id} - admin->>api: GET /forms/{form id} - admin->>api: GET /forms/{form id}/pages browser-->>user: show draft form page with task list else form creator decides to make form live user->>browser: click "Yes" and submits page browser->>admin: POST /forms/{form id}/make-live
payload: {forms_make_live_form"=>
{"confirm_make_live"=>"made_live"},
"form_id"=>"{form id"}} - admin->>api: POST /api/v1/forms/{form id}/make-live
payload: {includes all form attributes and values}
Controller Action doesn't use any - note over admin,api: Creates a new record in published_forms table,
with a copy of the form and all its pages
+ note over admin,admin: Creates a new record in published forms table,
with a copy of the form and all its pages
browser-->>user: show "Your form is live" confirmation page user->>browser: click "Continue to form details" link browser->>admin: GET /forms/{form id}/live - admin->>api: GET /api/v1/forms/{form id} - admin->>api: GET /api/v1/forms/{form id}/live browser-->>user: show live form page end ``` diff --git a/diagrams/sequence-diagrams/creating-a-form.md b/diagrams/sequence-diagrams/creating-a-form.md index ebe85e320..aa35a3aff 100644 --- a/diagrams/sequence-diagrams/creating-a-form.md +++ b/diagrams/sequence-diagrams/creating-a-form.md @@ -7,8 +7,6 @@ sequenceDiagram participant browser as Web Browser participant admin as forms-admin link admin: GitHub repo @ https://github.com/alphagov/forms-admin - participant api as forms-api - link api: GitHub repo @ https://github.com/alphagov/forms-api note right of user: user has already logged in @@ -17,13 +15,9 @@ sequenceDiagram browser-->>user: show "What is the name of your form?" page user->>browser: Give the form a name
click "Save and continue" button browser->>admin: POST /forms/new
payload: forms_change_name_form%5Bname%5D={form name} - admin->>api: POST /forms
{"name":"{form name}",
"submission_email":"",
"organisation_id":{user organisation id}} - api->>api: Create form - api-->>admin: {"id":{form id}} + admin->>admin: Create form admin-->>browser: 302 browser->>admin: GET /forms/{form id} - admin->>api: GET /forms/{form id} - admin->>api: GET /forms/{form id}/pages browser-->>user: show "Create a form" page ``` @@ -36,15 +30,11 @@ sequenceDiagram participant browser as Web Browser participant admin as forms-admin link admin: GitHub repo @ https://github.com/alphagov/forms-admin - participant api as forms-api - link api: GitHub repo @ https://github.com/alphagov/forms-api note right of user: On the "Create a form" page user->>browser: click "Add and edit your questions" link browser->>admin: GET /forms/1/pages/new/type-of-answer - admin->>api: GET /forms/{form id} - admin->>api: GET /forms/{form id}/pages browser-->>user: show "What kind of answer do you need to this question?" page @@ -59,9 +49,7 @@ sequenceDiagram user->>browser: Provide Question text, Hint text (optional), Question settings user->>browser: Click "Save and add next question" OR "Save question" button browser->>admin: POST /forms/{form id}/pages/new/question - admin->>api: POST /forms/{form id}/pages
{"question_text":,
"hint_text":,
"answer_type":,
"is_optional":,
"answer_settings":{"input_type":} - api->>api: create page - api-->>admin: 201 + admin->>admin: create page alt "Save and add next question" clicked admin-->>browser: 302 @@ -83,25 +71,18 @@ sequenceDiagram participant browser as Web Browser participant admin as forms-admin link admin: GitHub repo @ https://github.com/alphagov/forms-admin - participant api as forms-api - link api: GitHub repo @ https://github.com/alphagov/forms-api note right of user: form already created user->>browser: click "Add a declaration for people to agree to" link browser->>admin: GET /forms/{form id}/declaration - admin->>api: GET /forms/{form id} browser-->>user: show "Add a declaration" page user->>browser: Provide declaration
click "Save and continue" button browser->>admin: POST /forms/{form id}/declaration - admin->>api: GET /forms/{form id} - admin->>api: PUT /forms/{form id} - api->>api: Update form + admin->>admin: Update form admin-->>browser: 302 browser->>admin: GET /forms/{form id} - admin->>api: GET /forms/{form id} - admin->>api: GET /forms/{form id}/pages browser-->>user: show "Create a form" page ``` @@ -120,8 +101,6 @@ sequenceDiagram participant browser as Web Browser participant admin as forms-admin link admin: GitHub repo @ https://github.com/alphagov/forms-admin - participant api as forms-api - link api: GitHub repo @ https://github.com/alphagov/forms-api participant notify as GOV.UK Notify participant inbox as shared email inbox actor processor as form processor @@ -130,7 +109,6 @@ sequenceDiagram user->>browser: click "Set the email address for completed forms" link browser->>admin: GET /forms/{form id}/submission-email - admin->>api: GET /forms/{form id} browser-->>user: show "Set the email address for completed forms" page user->>browser: Provide email address
click "Save and continue" button browser->>admin: POST /forms/{form id}/submission-email @@ -139,7 +117,6 @@ sequenceDiagram notify->>inbox: Send email admin-->>browser: 302 browser->>admin: GET /forms/{form id}/email-code-sent - admin->>api: GET /forms/{form id} browser-->>user: show "Confirmation code sent" page inbox--)processor: read email @@ -147,12 +124,10 @@ sequenceDiagram user->>browser: click "Enter the email address confirmation code" link browser->>admin: GET /forms/{form id}/confirm-submission-email - admin->>api: GET /forms/{form id} browser-->>user: show "Enter the confirmation code" page user->>browser: enter code, click "Save and continue" button browser->>admin: POST /forms/{form id}/confirm-submission-email - admin->>api: GET /forms/{form id} admin->>admin: check code opt wrong code entered @@ -160,15 +135,12 @@ sequenceDiagram browser-->>user: show "Enter the confirmation code" page with error user->>browser: enter code, click "Save and continue" button browser->>admin: POST /forms/{form id}/confirm-submission-email - admin->>api: GET /forms/{form id} admin->>admin: check code end - admin->>api: PUT /forms/{form id} - api->>api: update form + admin->>admin: update form admin-->>browser: 302 browser->>admin: GET /forms/{form id}/submission-email-confirmed - admin->>api: GET /forms/{form id} browser-->>user: show "Email address confirmed" page ``` @@ -183,20 +155,15 @@ sequenceDiagram link admin: GitHub repo @ https://github.com/alphagov/forms-admin participant runner as forms-runner link runner: GitHub repo @ https://github.com/alphagov/forms-runner - participant api as forms-api - link api: GitHub repo @ https://github.com/alphagov/forms-api note right of user: At least one question has been added admin-->>user: show "Create a form" page user->>browser: Click "Preview this form in a new tab" link browser->>runner: GET /preview-form/{form id}/{form slug} - runner->>api: GET /forms/{form id} runner->>runner: determine start page runner-->>browser: 302 browser->>runner: GET /forms/{form id}/{form slug}/{start page id} - runner->>api: GET /forms/{form id} - runner->>api: GET /forms/{form id}/pages runner-->>browser: render form start page browser-->>user: show form preview in new tab ``` diff --git a/diagrams/sequence-diagrams/filling-in-a-form.md b/diagrams/sequence-diagrams/filling-in-a-form.md index 11eadcaa6..c4406bf69 100644 --- a/diagrams/sequence-diagrams/filling-in-a-form.md +++ b/diagrams/sequence-diagrams/filling-in-a-form.md @@ -6,7 +6,7 @@ sequenceDiagram participant browser as Web Browser participant govuk as GOV.UK website participant runner as forms-runner - participant api as forms-api + participant admin as forms-admin participant notify as GOV.UK Notify participant inbox as shared email inbox actor processor as Form processor @@ -18,21 +18,21 @@ sequenceDiagram user->>browser: Click link to form browser->>runner: GET /form/{form id}/{form slug} note over browser,runner: Start - runner->>api: GET /api/v1/forms/{form id}/live + runner->>admin: GET /api/v2/forms/{form id}/live runner->>runner: determine start page runner-->>browser: 302 browser->>runner: GET /form/{form id}/{form slug}/{start page id} - runner->>api: GET /api/v1/forms/{form id}/live + runner->>admin: GET /api/v2/forms/{form id}/live browser-->>user: show form loop for each form question user->>browser: Provide answer, click "Continue" browser->>runner: POST /form/{form id}/{form slug}/{page id} - runner->>api: GET /api/v1/forms/{form id}/live + runner->>admin: GET /api/v2/forms/{form id}/live runner->>runner: Save user session runner-->>browser: 302 browser->>runner: GET /form/{form id}/{form slug}/{next page id} - runner->>api: GET /api/v1/forms/{form id}/live + runner->>admin: GET /api/v2/forms/{form id}/live browser-->>user: Show next question end @@ -40,12 +40,12 @@ sequenceDiagram browser-->>user: Show check your answers page user->>browser: Click "Submit" browser->>runner: POST /form/{form id}/{form slug}/submit-answers - runner->>api: GET /api/v1/forms/{form id}/live + runner->>admin: GET /api/v2/forms/{form id}/live runner->>notify: client.send_email() runner->>runner: Delete user session runner-->>browser: 302 browser->>runner: GET /form/{form id}/{form slug}/submitted - runner->>api: GET /api/v1/forms/{form id}/live + runner->>admin: GET /api/v2/forms/{form id}/live browser-->>user: Show confirmation page notify->>inbox: Send email inbox->>processor: Read email @@ -60,12 +60,12 @@ sequenceDiagram actor user as Form filler participant browser as Web Browser participant runner as forms-runner - participant api as forms-api + participant admin as forms-admin participant notify as GOV.UK Notify user->>browser: Click link to form browser->>runner: GET /form/{form id}/{form slug} - runner->>api: GET /api/v1/forms/{form id}/live + runner->>admin: GET /api/v2/forms/{form id}/live runner-->browser: REDIRECT 302 (includes first page id) browser->>runner: GET /form/{form id}/{forms slug}/{page id} Note over browser,runner: A new session has started diff --git a/diagrams/sequence-diagrams/publishing-a-form.md b/diagrams/sequence-diagrams/publishing-a-form.md index 68d21de1e..41732da83 100644 --- a/diagrams/sequence-diagrams/publishing-a-form.md +++ b/diagrams/sequence-diagrams/publishing-a-form.md @@ -7,22 +7,16 @@ sequenceDiagram participant browser as Web Browser participant admin as forms-admin link admin: GitHub repo @ https://github.com/alphagov/forms-admin - participant api as forms-api - link api: GitHub repo @ https://github.com/alphagov/forms-api note right of user: All tasks except "Make your form live" have been completed admin-->>user: show "Create a form" page user->>browser: Click "Make your form live" link browser->>admin: GET /forms/{form id}/make-live - admin->>api: GET /api/v1/forms/{form id} browser-->>user: show "Make your form live" page user->>browser: Confirm making form live
click "Save and continue" button browser->>admin: POST /forms/{form id}/make-live - admin->>api: GET /api/v1/forms/{form id} - admin->>api: GET /api/v1/forms/{form id}/pages - admin->>api: POST /api/v1/forms/{form id}/make-live
payload: {includes all form attributes and values}
Controller Action doesn't use any browser-->>user: show "Your form is live" page user->>user: Copy URL for the form