Merge pull request #68 from OpenVic2Project/docs-architecture-and-schema

Docs architecture and schema

6 files changed, 193 insertions, 30 deletions

diff --git a/docs/README.md b/docs/README.md
index b6edf3a..5a4d160 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,11 @@
 # Documentation
 
 - [Contribution Quickstart Guide](contribution-quickstart-guide.md)
+- [General Program Architecture](general-program-architecture.md)
 - [Project File Structure](project-file-structure.md)
-- [C++ Style Guidlines](styleguide-cpp.md)
\ No newline at end of file
+- [C++ Style Guidelines](styleguide-cpp.md)
+
+## Simulation
+- [Goods](simulation/goods.md)
+- [Ideologies](simulation/ideologies.md)
+- [Provinces](simulation/provinces.md)
diff --git a/docs/general-program-architecture.md b/docs/general-program-architecture.md
new file mode 100644
index 0000000..533a8fa
--- /dev/null
+++ b/docs/general-program-architecture.md
@@ -0,0 +1,52 @@
+# Player-Game Interaction
+```mermaid
+sequenceDiagram
+actor Player
+participant UI as Godot
+participant Bridge as Godot-CPP Bridge
+participant Simulation
+participant Dataloader
+autonumber
+
+Player ->> UI: Program starts
+UI ->> Bridge: Godot autoloaders fire
+Bridge ->> Dataloader: Signal to load Simulation
+Dataloader ->> Simulation: Read in data from file(s)
+Simulation ->> Bridge:  Simulation finished loading data
+Bridge ->> UI: Autoloaders finish
+UI ->> Player: Display Main Menu
+Player ->> UI: Press "New Game" or<br>"Load Game" button
+UI ->> Bridge: Begin new Game Session
+Bridge ->> Simulation: Start new Game Session
+Simulation -->> Dataloader: Load previous savegame<br>(If necessary)
+Dataloader -->> Simulation: 
+Simulation ->> Bridge: Provide information necessary<br>for UI and visual elements
+Bridge ->> UI: Signal that Game Session<br> is ready for interaction
+UI ->> Player: Present to Player
+
+loop Core Game Loop
+Player ->> UI: Interact with game controls
+UI ->> Bridge: Convey player intent<br>according to UI<br>handler functions 
+Bridge ->> Simulation: Relay changes to entities<br>controlled by the Player
+Note over Simulation: When unpaused:
+Simulation ->> Simulation: Advance to next in-game day<br>according to game speed<br>and update Simulation state
+Simulation ->> Bridge: Inform of relevant<br>changes to game state
+Bridge ->> UI: Update UI and map
+UI ->> Player: Display new data
+end
+
+opt Save Game
+Player ->> UI: Press "Save Game" button<br>in the Game Session Menu
+UI ->> Bridge: Demand that the current<br>game state is saved
+Bridge ->> Simulation: Begin save routines
+Simulation ->> Dataloader: Write current state to disk
+Simulation ->> Bridge: Save routines completed
+Bridge ->> UI: Trigger "successful save"<br>message
+UI ->> Player: Give visual confirmation<br>of successful save
+end
+
+Player ->> UI: Press "Exit Game" button
+UI ->> Player: Give a "Confirm quit (Y/N)"<br>dialog window
+Player ->> UI: Confirm intent to quit program
+UI ->> Player: Program closes
+```
\ No newline at end of file
diff --git a/docs/simulation/goods.md b/docs/simulation/goods.md
index 241362b..15b4864 100644
--- a/docs/simulation/goods.md
+++ b/docs/simulation/goods.md
@@ -52,18 +52,18 @@ classDiagram
 |timber|Raw|0.90|146 72 17|True|True|False|False|
 |tropical_wood|Raw|5.40|213 177 118|True|True|False|False|
 |wool|Raw|0.70|234 195 158|True|True|False|False|
-|steel|Industry|4.70|95 128 147|False|True|False|False|
-|cement|Industry|16.00|185 187 164|True|True|False|False|
-|machine_parts|Industry|36.50|177 198 196|False|True|False|False|
-|glass|Industry|2.90|201 200 199|True|True|False|False|
-|fuel|Industry|25.00|145 110 89|False|True|False|False|
-|fertilizer|Industry|10.00|133 101 35|True|True|False|False|
-|explosives|Industry|20.00|192 68 20|False|True|False|False|
-|clipper_convoy|Industry|42.00|21 65 30|False|True|False|True|
-|steamer_convoy|Industry|65.00|76 18 0|False|True|False|True|
-|electric_gear|Industry|16.00|255 255 0|False|True|False|False|
-|fabric|Industry|1.80|186 50 40|True|True|False|False|
-|lumber|Industry|1.00|180 94 26|True|True|False|False|
+|steel|Industrial|4.70|95 128 147|False|True|False|False|
+|cement|Industrial|16.00|185 187 164|True|True|False|False|
+|machine_parts|Industrial|36.50|177 198 196|False|True|False|False|
+|glass|Industrial|2.90|201 200 199|True|True|False|False|
+|fuel|Industrial|25.00|145 110 89|False|True|False|False|
+|fertilizer|Industrial|10.00|133 101 35|True|True|False|False|
+|explosives|Industrial|20.00|192 68 20|False|True|False|False|
+|clipper_convoy|Industrial|42.00|21 65 30|False|True|False|True|
+|steamer_convoy|Industrial|65.00|76 18 0|False|True|False|True|
+|electric_gear|Industrial|16.00|255 255 0|False|True|False|False|
+|fabric|Industrial|1.80|186 50 40|True|True|False|False|
+|lumber|Industrial|1.00|180 94 26|True|True|False|False|
 |paper|Consumer|3.40|216 185 77|True|True|False|False|
 |cattle|Consumer|2.00|84 227 40|True|True|False|False|
 |fish|Consumer|1.50|128 98 73|True|True|False|False|
@@ -106,18 +106,18 @@ classDiagram
 |timber|Raw|0.90|146 72 17|True|True|False|False|
 |tropical_wood|Raw|5.40|213 177 118|True|True|False|False|
 |wool|Raw|0.70|234 195 158|True|True|False|False|
-|steel|Industry|4.70|95 128 147|False|True|False|False|
-|cement|Industry|16.00|185 187 164|True|True|False|False|
-|machine_parts|Industry|36.50|177 198 196|False|True|False|False|
-|glass|Industry|2.90|201 200 199|True|True|False|False|
-|fuel|Industry|25.00|145 110 89|False|True|False|False|
-|fertilizer|Industry|10.00|133 101 35|True|True|False|False|
-|explosives|Industry|20.00|192 68 20|False|True|False|False|
-|clipper_convoy|Industry|42.00|21 65 30|False|True|False|True|
-|steamer_convoy|Industry|65.00|76 18 0|False|True|False|True|
-|electric_gear|Industry|16.00|255 255 0|False|True|False|False|
-|fabric|Industry|1.80|186 50 40|True|True|False|False|
-|lumber|Industry|1.00|180 94 26|True|True|False|False|
+|steel|Industrial|4.70|95 128 147|False|True|False|False|
+|cement|Industrial|16.00|185 187 164|True|True|False|False|
+|machine_parts|Industrial|36.50|177 198 196|False|True|False|False|
+|glass|Industrial|2.90|201 200 199|True|True|False|False|
+|fuel|Industrial|25.00|145 110 89|False|True|False|False|
+|fertilizer|Industrial|10.00|133 101 35|True|True|False|False|
+|explosives|Industrial|20.00|192 68 20|False|True|False|False|
+|clipper_convoy|Industrial|42.00|21 65 30|False|True|False|True|
+|steamer_convoy|Industrial|65.00|76 18 0|False|True|False|True|
+|electric_gear|Industrial|16.00|255 255 0|False|True|False|False|
+|fabric|Industrial|1.80|186 50 40|True|True|False|False|
+|lumber|Industrial|1.00|180 94 26|True|True|False|False|
 |paper|Consumer|3.40|216 185 77|True|True|False|False|
 |cattle|Consumer|2.00|84 227 40|True|True|False|False|
 |fish|Consumer|1.50|128 98 73|True|True|False|False|
diff --git a/docs/simulation/ideologies.md b/docs/simulation/ideologies.md
index 4d91056..f56cda7 100644
--- a/docs/simulation/ideologies.md
+++ b/docs/simulation/ideologies.md
@@ -9,16 +9,17 @@ classDiagram
 
     class IdeologicalGroup {
         <<enumeration>>
-        Facist
+        Fascist
         Conservative
         Socialist
         Liberal
     }
 
     class Ideology {
+        + String id
         + IdeologicalGroup group
-        + Date earliest_date
-        + boolean uncivilized_nations
+        + Date earliestDate
+        + boolean uncivilizedNations
         + Colour colour
     }
 
@@ -38,7 +39,7 @@ classDiagram
 |anarcho_liberal|liberal|1845/01/01|True|#96960A|
 |socialist|socialist|1860/01/01|False|#FF0000|
 |communist|socialist|1865/01/01|False|#960A0A|
-|facist|facist|1905/01/01|False|#3C3C3C|
+|fascist|fascist|1905/01/01|False|#3C3C3C|
 
 ### John Cena 
 
@@ -50,7 +51,7 @@ classDiagram
 |anarcho_liberal|liberal|1845/01/01|True|#96960A|
 |socialist|socialist|1860/01/01|False|#FF0000|
 |communist|socialist|1865/01/01|False|#960A0A|
-|facist|facist|1905/01/01|False|#3C3C3C|
+|fascist|fascist|1905/01/01|False|#3C3C3C|
 
 ## References
 
diff --git a/docs/simulation/provinces.md b/docs/simulation/provinces.md
new file mode 100644
index 0000000..88eea50
--- /dev/null
+++ b/docs/simulation/provinces.md
@@ -0,0 +1,104 @@
+# OpenVic2 Provinces
+
+## OpenVic2 Structure
+
+```mermaid
+classDiagram
+	class Province {
+		Int64 id                 
+		string provinceName    
+		string tradeGood       
+		Int64 lifeRating         
+		bool hasLegalSlavery   
+
+		Int64 fortLevel          
+		Int64 navalBaseLevel     
+		Int64 railroadLevel
+		
+		string regionId
+		string continentId
+	}
+```
+<!-- The following attributes will need to be added when Nations are added
+	NationId owningNation
+	NationId controllingNation
+	NationId[] coreNations
+-->
+
+# Dataloading
+To populate the Province structures, the following data files will be loaded in the following order:
+1. `provinces.json`
+2. `regions.json`
+3. `continents.json`
+
+## 1. Provinces.json
+The `provinces.json` file shall look like:
+```json
+{
+	"provinces": [
+		{"id": 123, "provinceName": "abc", ...},
+		...
+	]
+}
+```
+Where the `"provinces"` array contains valid province JSON objects which conform to the following key-value pairs:
+| Key | type | Required? | Default Value |
+|--|--|--|--|
+| id              | int    | required | N/A       |
+| provinceName    | string | required | N/A       |
+| tradeGood       | string | optional | "no_good" |
+| lifeRating      | int    | optional | 0         |
+| hasLegalSlavery | bool   | optional | false     |
+| fortLevel       | int    | optional | 0         |
+| navalBaseLevel  | int    | optional | 0         |
+| railroadLevel   | int    | optional | 0         |
+### Notes on values:
+- The values of `fortLevel`, `navalBaseLevel`, and `railroadLevel` may not be negative
+- The value of `tradeGood` may only be a Good Identifier string as defined in [goods.md](goods.md) or `"no_good"`
+
+
+## 2. Regions.json
+The `regions.json` file shall look like:
+```json
+{
+	"regions": [
+		{"id": "abc", "provinceIds": [123, 456, ...]},
+		...
+	]
+}
+```
+Where the `"regions"` array contains valid region JSON objects which conform to the following key-value pairs:
+| Key | type | Required? | Default Value |
+|--|--|--|--|
+| id             | string     | required | N/A       |
+| provinceIds    | Array[int] | required | N/A       |
+### Notes on values:
+- The value of `id` may not be an empty string
+- The value of `id` must be unique among all continents
+- `provinceIds` may be an empty array; an empty array should be logged as a warning
+- The content of `provinceIds` may only be Province Identifier integers as defined above
+- A province may only belong to a single region, any attempts to re-assign a province's region during dataloading should be ignored and logged as an error
+
+
+
+## 3. Continents.json
+The `continents.json` file shall look like:
+```json
+{
+	"continents": [
+		{"id": "abc", "provinceIds": [123, 456, ...]},
+		...
+	]
+}
+```
+Where the `"continents"` array contains valid continent JSON objects which conform to the following key-value pairs:
+| Key | type | Required? | Default Value |
+|--|--|--|--|
+| id             | string     | required | N/A       |
+| provinceIds    | Array[int] | required | N/A       |
+### Notes on values:
+- The value of `id` may not be an empty string
+- The value of `id` must be unique among all continents
+- `provinceIds` may be an empty array; an empty array should be logged as a warning
+- The content of `provinceIds` may only be Province Identifier integers as defined in [provinces.md](provinces.md)
+- A province may only belong to a single continent, any attempts to re-assign a province's continent during dataloading should be ignored and logged as an error
diff --git a/docs/simulation/sim_doc_format.md b/docs/simulation/sim-doc-format.md
index 68bd905..68bd905 100644
--- a/docs/simulation/sim_doc_format.md
+++ b/docs/simulation/sim-doc-format.md