DONE: layout letter with letterhead and footer, notification for newly...

docs/membership_application-db_design.md

@@ -0,0 +1,283 @@
+The differences are actually quite small, but they're important because they reflect the **real business process** more accurately.
+
+## Earlier Design
+
+I initially assumed:
+
+```text
+Management
+    |
+Approve/Reject
+    |
+Board
+    |
+Pass/Fail
+    |
+General Manager
+    |
+Approve/Reject
+```
+
+Therefore I proposed:
+
+```text
+application_management_reviews
+application_board_evaluations
+application_gm_decisions
+```
+
+or later:
+
+```text
+application_reviews
+    - MANAGEMENT
+    - BOARD
+    - GM
+```
+
+because I thought the GM was making a decision.
+
+---
+
+## Current Design
+
+After your clarification:
+
+> The outcome is already known after board evaluation.
+>
+> The GM only prints the result letter and notifies the applicant.
+
+The workflow is actually:
+
+```text
+Management
+    |
+Approve/Reject
+    |
+Board
+    |
+Pass/Fail
+    |
+General Manager
+(Print letter)
+(Send email)
+```
+
+The GM is no longer a reviewer.
+
+Therefore:
+
+### Removed
+
+```text
+application_gm_decisions
+```
+
+because there is no GM decision to store.
+
+---
+
+### Added
+
+```text
+application_notifications
+```
+
+because the GM's responsibility is administrative:
+
+* Generate acceptance/rejection letter
+* Send email
+* Mark notification completed
+
+Example:
+
+| application_id | letter_generated_at | email_sent_at    |
+| -------------- | ------------------- | ---------------- |
+| 1001           | 2026-06-01 10:00    | 2026-06-01 10:05 |
+
+---
+
+## Status Changes
+
+### Earlier
+
+```text
+MANAGEMENT_REJECTED
+GM_REJECTED
+APPROVED
+ACCOUNT_CREATED
+```
+
+### Current
+
+```text
+MANAGEMENT_REJECTED
+BOARD_FAILED
+BOARD_PASSED
+NOTIFICATION_PENDING
+COMPLETED
+```
+
+because the board determines the outcome.
+
+---
+
+## Review Tables
+
+### Earlier
+
+I proposed three tables:
+
+```text
+application_management_reviews
+application_board_evaluations
+application_gm_decisions
+```
+
+Then simplified to:
+
+```text
+application_reviews
+```
+
+with:
+
+```text
+MANAGEMENT
+BOARD
+GM
+```
+
+### Current
+
+Still:
+
+```text
+application_reviews
+```
+
+but only:
+
+```text
+MANAGEMENT
+BOARD
+```
+
+No GM stage.
+
+---
+
+## What I Would Simplify Even Further
+
+Looking at your process, I'd actually make it even leaner.
+
+### membership_applications
+
+Add outcome fields directly:
+
+```sql
+membership_applications
+-----------------------
+id
+
+status
+
+management_result
+board_result
+
+notification_sent_at
+
+submitted_at
+completed_at
+```
+
+Where:
+
+```text
+management_result
+-----------------
+PENDING
+APPROVED
+REJECTED
+
+board_result
+------------
+PENDING
+PASS
+FAIL
+```
+
+Then you might not even need `application_reviews` if:
+
+* One management review only
+* One board evaluation only
+
+You could store everything directly on the application record.
+
+Example:
+
+| application | mgmt     | board |
+| ----------- | -------- | ----- |
+| APP001      | APPROVED | PASS  |
+| APP002      | APPROVED | FAIL  |
+| APP003      | REJECTED | NULL  |
+
+---
+
+## My Recommendation
+
+For your described workflow, I'd use:
+
+```text
+membership_applications
+application_applicants
+application_heirs
+application_documents
+application_references
+application_reviews
+application_notifications
+users
+members
+```
+
+and remove:
+
+```text
+application_management_reviews
+application_board_evaluations
+application_gm_decisions
+application_workflow_logs
+```
+
+unless you have a compliance/audit requirement.
+
+### Why remove `application_workflow_logs`?
+
+If your workflow is fixed and simple:
+
+* Management reviews once.
+* Board evaluates once.
+* GM sends notification once.
+
+Then:
+
+```text
+application_reviews
+```
+
+already tells you who reviewed and when.
+
+A workflow log becomes useful only when you need things like:
+
+```text
+Reopened
+Returned for correction
+Resubmitted
+Reassigned
+Escalated
+Withdrawn
+```
+
+If those scenarios don't exist, it's additional complexity without much benefit.
+
+So the "latest" design is mainly different because **the GM is no longer treated as a decision-maker**, only as a notification handler. That removes an entire approval layer from the data model and simplifies the workflow considerably.