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