Fill Readme and add initial diagrams

README.md

@@ -1,8 +1,30 @@
-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 create `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.
+
+
+## Developer Setup
 
 ```bash
 direnv allow

compareware-nf.plantuml

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

compareware.plantuml

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