Add architecture and data flow diagrams

ARCHITECTURE.md

@@ -56,6 +56,16 @@ SynthOps
 
 ---
 
+## Architecture Diagrams
+
+Supporting diagrams:
+
+- [High-Level Architecture Diagram](docs/diagrams/high_level_architecture.md)
+- [Adult Social Care Data Flow Diagram](docs/diagrams/adult_social_care_data_flow.md)
+- [Adult Social Care Table Relationship Diagram](docs/diagrams/adult_social_care_relationships.md)
+
+---
+
 ## Repository Structure
 
 ```text

CHANGELOG.md

@@ -56,6 +56,7 @@ SynthOps is currently in early development and has not yet published a stable re
 - Updated Adult Social Care documentation to describe the implemented resident lifecycle generator.
 - Updated example generation script to output both care homes and residents.
 - Added Adult Social Care data dictionary documenting implemented tables, columns, relationships, valid values and data quality rules.
+- Added high-level architecture, Adult Social Care data flow and Adult Social Care table relationship diagrams.
 
 ---
 

docs/diagrams/adult_social_care_data_flow.md

@@ -0,0 +1,45 @@
+# Adult Social Care Data Flow Diagram
+
+This diagram shows the current Adult Social Care sample generation flow.
+
+The `care_homes` table is generated first. The `residents` table is then generated from the care homes output so that resident records can link to valid care homes and match active occupancy counts.
+
+```mermaid
+flowchart TD
+    A[User runs example script] --> B[Generate care_homes]
+    B --> C[care_homes DataFrame]
+    C --> D[Generate residents]
+    D --> E[residents DataFrame]
+
+    C --> F[Write care_homes.csv]
+    E --> G[Write residents.csv]
+
+    B --> H[Use core ID utilities]
+    B --> I[Use core date utilities]
+    D --> H
+    D --> I
+
+    F --> J[data/sample/adult_social_care/]
+    G --> J
+
+    K[Pytest] --> L[Validate generator behaviour]
+    L --> M[Check IDs, dates, relationships and lifecycle rules]
+```
+
+## Current Output Files
+
+```text
+data/sample/adult_social_care/care_homes.csv
+data/sample/adult_social_care/residents.csv
+```
+
+## Notes
+
+The residents generator depends on the care homes output.
+
+This dependency ensures:
+
+- every resident links to a valid care home
+- active resident counts match `care_homes.current_residents`
+- historical resident volume can be influenced by `turnover_profile`
+- future care-needs, incidents and observations can be linked to valid resident stay periods

docs/diagrams/adult_social_care_relationships.md

@@ -0,0 +1,101 @@
+# Adult Social Care Table Relationship Diagram
+
+This diagram shows the current and planned table relationships for the Adult Social Care domain module.
+
+```mermaid
+erDiagram
+    CARE_HOMES ||--o{ RESIDENTS : has
+    RESIDENTS ||--o{ RESIDENT_CARE_NEEDS_HISTORY : will_have
+    CARE_HOMES ||--o{ STAFF : will_have
+    CARE_HOMES ||--o{ SHIFTS : will_have
+    STAFF ||--o{ SHIFTS : will_work
+    RESIDENTS ||--o{ INCIDENTS : will_have
+    CARE_HOMES ||--o{ INCIDENTS : will_record
+    RESIDENTS ||--o{ OBSERVATIONS : will_have
+    CARE_HOMES ||--o{ HANDOVER_NOTES : will_have
+
+    CARE_HOMES {
+        string care_home_id PK
+        string care_home_name
+        string region
+        string local_authority
+        string care_home_type
+        string turnover_profile
+        int bed_capacity
+        float occupancy_rate
+        int current_residents
+        string cqc_rating
+        date opened_date
+    }
+
+    RESIDENTS {
+        string resident_id PK
+        string care_home_id FK
+        date date_of_birth
+        string gender
+        date admission_date
+        date exit_date
+        string exit_reason
+        string status_at_dataset_end
+    }
+
+    RESIDENT_CARE_NEEDS_HISTORY {
+        string care_needs_assessment_id PK
+        string resident_id FK
+        date assessment_date
+        string dependency_level
+        string mobility_support_level
+        string personal_care_support_level
+        string dementia_support
+        string nutrition_risk
+        string falls_risk
+        string review_reason
+    }
+
+    STAFF {
+        string staff_id PK
+        string care_home_id FK
+    }
+
+    SHIFTS {
+        string shift_id PK
+        string care_home_id FK
+        string staff_id FK
+    }
+
+    INCIDENTS {
+        string incident_id PK
+        string resident_id FK
+        string care_home_id FK
+    }
+
+    OBSERVATIONS {
+        string observation_id PK
+        string resident_id FK
+    }
+
+    HANDOVER_NOTES {
+        string handover_note_id PK
+        string care_home_id FK
+    }
+```
+
+## Implemented Tables
+
+- `care_homes`
+- `residents`
+
+## Planned Tables
+
+- `resident_care_needs_history`
+- `staff`
+- `shifts`
+- `incidents`
+- `observations`
+- `handover_notes`
+
+## Notes
+
+Only `care_homes` and `residents` are currently implemented.
+
+Planned tables are shown to explain the intended direction of the Adult Social Care module. They should not be described as implemented until the relevant generators, tests, documentation and sample outputs exist.

docs/diagrams/high_level_architecture.md

@@ -0,0 +1,47 @@
+# High-Level Architecture Diagram
+
+This diagram shows the current high-level architecture of SynthOps.
+
+SynthOps separates reusable core utilities from domain-specific generation logic. Adult Social Care is the first implemented domain module, while future domains can reuse the same core utilities.
+
+```mermaid
+flowchart TD
+    A[SynthOps] --> B[Core Utilities]
+    A --> C[Domain Modules]
+    A --> D[Examples]
+    A --> E[Tests]
+    A --> F[Documentation]
+
+    B --> B1[ID Generation]
+    B --> B2[Date Utilities]
+    B --> B3[Future Validation Helpers]
+    B --> B4[Future Export Helpers]
+
+    C --> C1[Adult Social Care]
+    C --> C2[Future Finance Operations]
+    C --> C3[Future Construction Operations]
+    C --> C4[Future SaaS Metrics]
+    C --> C5[Future Workforce Analytics]
+
+    C1 --> C1A[Care Homes Generator]
+    C1 --> C1B[Residents Generator]
+    C1 --> C1C[Planned Care Needs History]
+    C1 --> C1D[Planned Staff, Shifts and Incidents]
+
+    D --> D1[Generate Adult Social Care Sample]
+    E --> E1[Pytest Test Suite]
+    F --> F1[README]
+    F --> F2[Architecture]
+    F --> F3[Roadmap]
+    F --> F4[Domain Docs]
+    F --> F5[ADRs]
+    F --> F6[Data Dictionary]
+```
+
+## Notes
+
+The core package should remain domain-neutral.
+
+Domain-specific logic should live inside `src/synthops/domains/`.
+
+Adult Social Care is the first implemented domain, not the entire product.

docs/domains/adult_social_care.md

@@ -35,6 +35,8 @@ Planned tables:
 ## Related Documentation
 
 - [Adult Social Care Data Dictionary](adult_social_care_data_dictionary.md)
+- [Adult Social Care Data Flow Diagram](../diagrams/adult_social_care_data_flow.md)
+- [Adult Social Care Table Relationship Diagram](../diagrams/adult_social_care_relationships.md)
 
 ---