Add some BU documentation

communitiesuk · Jan 29, 2025 · 9c35ceb · 9c35ceb
1 parent 5b3c574
commit 9c35ceb
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 2 deletions.
diff --git a/docs/adr/index.md b/docs/adr/index.md
@@ -1,6 +1,6 @@
 ---
 has_children: true
-nav_order: 11
+nav_order: 12
 ---
 
 # Architecture decisions

diff --git a/docs/bulk_upload.md b/docs/bulk_upload.md
@@ -0,0 +1,43 @@
+---
+nav_order: 11
+---
+
+# Bulk Upload
+
+Bulk upload functionality allows users to upload multiple logs using a csv file.
+
+## How Bulk Upload works
+
+Bulk upload file can be uploaded for a specific log type (sales or lettings) for a specific year. During crossover period we ask which collection year the file is for, otherwise we assume the Bulk Upload is for the current year.
+
+When a bulk upload file is successfully uploaded on the service, it:
+- Saves a BulkUpload record in the database
+- Uploads the file to S3
+- Schedules `ProcessBulkUploadJob`
+
+### Bulk upload service
+
+There are several outcomes to a bulk upload:
+- Successful upload
+- Partial upload: upload has errors but partial logs can be created, need a user approval
+- Errors in bulk upload: errors on important fields, or in the template. Logs can't be created and email with errors is sent to the user
+
+![Bulk Upload Flow](https://raw.githubusercontent.com/communitiesuk/submit-social-housing-lettings-and-sales-data/main/docs/images/bu_flow_diagram.png)
+
+### Bulk upload processing
+
+Most of BU processing logic is in `BulkUpload::Processor`. It chooses the correct `Validator` and `LogCreator` classes for the log type and uses them to process the file.
+
+![Bulk Upload Processing](https://raw.githubusercontent.com/communitiesuk/submit-social-housing-lettings-and-sales-data/main/docs/images/bu_processor.png)
+
+Main differences between different collection years would be in `CsvParsers` and `RowParsers`.
+
+#### Row parser
+- Maps any values from a csv row into values saved internally
+- Maps any validations into errors for bulk uploads by associating them with relevant fields
+- Adds any additional validations that might only make sense in BU (for example, validation that might not relevant in single log submission due to routing)
+
+### Csv parser
+- Holds template specific information
+  - Header information
+  - Row and field information
diff --git a/docs/documentation_website.md b/docs/documentation_website.md
@@ -1,5 +1,5 @@
 ---
-nav_order: 12
+nav_order: 13
 ---
 
 # This documentation website

diff --git a/docs/images/bu_flow_diagram.png b/docs/images/bu_flow_diagram.png
diff --git a/docs/images/bu_processor.png b/docs/images/bu_processor.png