Update Readme and Diagrams

README.md

@@ -1,10 +1,40 @@
-Example for Multi Record Forms
+# [CompareWare](https://compareware.org)
 
-Announced on https://github.com/digitallyinduced/ihp/releases/tag/v1.1.0
+## Use-Cases
+- Authorised users can create `Items`: Working, no authorisations
+- `Items` can have `Tags`: Implemented
 
-## Installation
+### To Implement
+- Authenticated `Users` can write `Reviews` referencing one or more `Items` and `Tag` them (for example with a URL linking to a more in-depth review)
+- `Users` can trust (the reviews of) other users,
+  creating a web of trust
+
+## Database Design
+`Tags` are Key-Value like in [OpenStreetMap](https://wiki.openstreetmap.org/wiki/Tags) or Wikidata,
+that is why they need own tables.
+Initially I planned having a shared `Tags` table for both `Reviews` and `Items`,
+but that would have been impractical because a Tag either belongs to a Review or an Item,
+so two separate tables would have needed to been set up to track the referenced object,
+with a risk of anomalies:
+Technically there then could be no mapping in either table for a Tag, or two,
+both of which are semantically incorrect -
+because a Tag without reference is useless
+and editing the Tag value for an `Item` should not affect a `Review` and vice versa.
+Considering the simplicity of a Tag,
+creating two separate tables prevents those cases without overhead
+and normalizes the schema.
+
+![CompareWare Overview Entity Relationship Diagram](compareware-erd.png)
+
+Of course, every many-to-many relationship needs another table
+to be represented in a normalized well,
+which the diagram of the actual structure used in the code illustrates:
+
+TODO
+
+## Developer Setup
 
 ```bash
 direnv allow
 devenv up
-```
+```

compareware-erd.plantuml

@@ -0,0 +1,47 @@
+@startuml compareware-erd
+skinparam linetype ortho
+hide circle
+left to right direction
+'!theme sandstone
+!theme blueprint
+
+entity User {
+    Id: Autoumber
+    --
+    (UNIQUE) Name: String
+    Pass: String
+}
+
+entity Item {
+    WikidataId: String
+    --
+}
+
+entity Review {
+    Id: Autoumber
+    --
+    (FK) AuthorId
+    Text: String
+}
+
+entity ItemTag {
+    Id: Autoumber
+    --
+    (INDEX) Key: String
+    Value: String
+}
+
+entity ReviewTag {
+    Id: Autoumber
+    --
+    (INDEX) Key: String
+    Value: String
+}
+
+User ||--o{ Review::AuthorId: Writes
+Item ||--o{ ItemTag
+Review ||--o{ ReviewTag
+Item }|--o{ Review
+User }|--|{ User: Trusts
+
+@enduml