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

Docs architecture and schema

4 files changed, 134 insertions, 29 deletions

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