From 70e999f465c94f749deebcb254b4067cb1cd3f02 Mon Sep 17 00:00:00 2001
From: xeruf <27jf@pm.me>
Date: Wed, 10 Apr 2024 14:20:54 +0200
Subject: [PATCH] Fill Readme and add initial diagrams

---
 README.md               | 30 +++++++++++++++++---
 compareware-nf.plantuml | 62 +++++++++++++++++++++++++++++++++++++++++
 compareware.plantuml    | 41 +++++++++++++++++++++++++++
 3 files changed, 129 insertions(+), 4 deletions(-)
 create mode 100644 compareware-nf.plantuml
 create mode 100644 compareware.plantuml

diff --git a/README.md b/README.md
index 4089a83..48bf11d 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,32 @@
-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
 devenv up
-```
\ No newline at end of file
+```
diff --git a/compareware-nf.plantuml b/compareware-nf.plantuml
new file mode 100644
index 0000000..eb46665
--- /dev/null
+++ b/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
diff --git a/compareware.plantuml b/compareware.plantuml
new file mode 100644
index 0000000..de45e24
--- /dev/null
+++ b/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