From 3c73358a593871adc4af3601e843288d41e21dec Mon Sep 17 00:00:00 2001 From: Celine Hagen Date: Tue, 6 Oct 2026 11:12:12 +0200 Subject: [PATCH] chore/oppdatert-readme --- README.md | 243 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 140 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 923f7a9..61a8fd8 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ -# T01-Project 2 - # Wine not? 🍷 -“Wine not?” er en webapplikasjon for å søke etter, utforske og lære mer om vin og vinregioner samt kunne lagre sine favorittviner til senere. +“Wine not?” er en webapplikasjon for å søke etter, utforske og lære mer om vin samt kunne lagre sine favorittviner til senere. -Målet er å lage en oversiktlig og visuelt interessant vinkatalog hvor brukeren både kan finne bestemte viner og oppdage nye gjennom søk, filtrering og geografisk utforskning. +Målet er å lage en oversiktlig og visuelt interessant vinkatalog hvor brukeren både kan finne bestemte viner og oppdage nye gjennom søk, filtrering og mer utforskende funksjoner basert på smak, mat og lignende viner. --- @@ -27,7 +25,10 @@ Denne innleveringen består av en spesifikasjon av den planlagte løsningen. Vi Brukeren skal kunne søke etter viner, filtrere og sortere resultater og åpne hver vin for å få mer informasjon. -I tillegg skal applikasjonen ha en egen side med et interaktivt kart hvor brukeren kan utforske ulike vinregioner og få opp informasjon om regionen og viner som kommer derfra. +I tillegg skal applikasjonen ha flere utforskende funksjoner som gjør det mulig å finne vin uten å vite nøyaktig hva man leter etter. På forsiden skal brukeren kunne utforske viner basert på smaksegenskaper som fylde og syre. + + +Applikasjonen skal også ha egne undersider for **Find wine by food**, hvor brukeren kan finne viner som passer til ulike typer mat, og **Wine DNA**, hvor brukeren kan finne viner som lignet på en vin de allerede liker Brukere skal også kunne opprette en konto og lagre viner som favoritter. @@ -49,7 +50,7 @@ Brukeren skal kunne: - se søkeresultater i en liste - filtrere resultatene - sortere resultatene -- åpne en vin for å se mer informasjon ? +- åpne en vin for å se mer informasjon Aktuelle filtre kan være: @@ -60,6 +61,8 @@ Aktuelle filtre kan være: - druetype - vintype - årgang +- fylde +- syrenivå Aktuelle sorteringsmuligheter kan være: @@ -99,89 +102,94 @@ Aktuelle data for en vin er: - rating -Fra detaljsiden skal brukeren også kunne navigere videre til regionen vinen kommer fra. +Fra detaljsiden skal brukeren også kunne lagre vinen som favoritt og åpne Wine DNA for å finne lignende viner. --- -## Utforsk vinregioner - - -Applikasjonen skal ha en egen side hvor brukeren kan utforske vin geografisk. +## Utforsk vin på nye måter -Et interaktivt kart skal gjøre det mulig å velge en vinregion, for eksempel: +Applikasjonen skal ha flere funksjoner som gjør det mulig å oppdage vin på andre måter enn gjennom vanlig søk. -- Bordeaux -- Bourgogne -- Champagne -- Toscana -- Piemonte +### Explore by taste +**Explore by taste** skal være en sentral del av forsiden. -Når en region velges, skal brukeren få opp informasjon om regionen og se viner fra dette området. +Her skal brukeren kunne utforske viner visuelt basert på smaksegenskaper som fylde og syre. Viner kan for eksempel plasseres i en interaktiv visualisering hvor den ene aksen viser fylde og den andre syrenivå. -Kartet skal ikke være den eneste måten å velge region på. Det skal også finnes en alternativ løsning, for eksempel nedtrekksmenyer eller en liste, slik at funksjonaliteten er tilgjengelig også for brukere som ikke kan bruke det visuelle kartet. +Brukeren skal kunne kombinere denne utforskningen med filtre som vintype, drue, land eller region. Ved å velge en vin i visualiseringen skal brukeren få en kort forhåndsvisning og kunne gå videre til detaljsiden. ---- +### Find wine by food +På undersiden **Find wine by food** skal brukeren kunne velge hvilken type mat vinen skal passe til. -## Bruker og favoritter +Eksempler på matkategorier kan være: +pasta +storfe +fisk +ost +sterk mat -Det skal være mulig å registrere seg og logge inn. +Applikasjonen skal deretter vise viner som passer til den valgte matkategorien. Brukeren skal også kunne filtrere resultatene videre. -Innloggede brukere skal kunne lagre viner som favoritter. +### Wine DNA +På undersiden **Wine DNA** skal brukeren kunne finne viner som ligner på en vin de allerede liker. -Favorittene skal lagres i databasen og være tilgjengelige igjen neste gang brukeren logger inn. +Likheter kan beregnes ut fra egenskaper som: +druetype +vintype +region +fylde +syrenivå +alkoholprosent +rating -Dette vil være den brukergenererte informasjonen i systemet. +Målet er ikke bare å vise lignende viner, men også å forklare hvorfor de matcher, for eksempel gjennom informasjon som «samme drue», «lignende fylde» eller «samme region». --- -## Planlagte sider +## Bruker og favoritter -### Home +Det skal være mulig å registrere seg og logge inn. -Forsiden skal introdusere applikasjonen og gi brukeren en enkel inngang til søk og utforskning. +Innloggede brukere skal kunne lagre viner som favoritter. -### Wines +Favorittene skal lagres i databasen og være tilgjengelige igjen neste gang brukeren logger inn. -En søkbar katalog over vinene i databasen. +Dette vil være den brukergenererte informasjonen i systemet. -Her skal brukeren kunne: +--- -- søke -- filtrere -- sortere -- åpne viner +## Planlagte sider -### Wine Details +### Home -Detaljside for én vin med informasjon om blant annet produsent, druer, region, årgang og vintype. +Forsiden skal introdusere applikasjonen og gi brukeren en enkel inngang til søk og utforskning. Brukeren skal kunne klikke på hver vin for å få opp mer informasjon om blant annet produsent, druer, region, årganger, alkoholprosent, fylde, syrenivå og rating. -### Regions +**Explore by taste** skal være en sentral del av forsiden, slik at brukeren raskt kan begynne å utforske viner basert på smaksegenskaper. -Interaktivt kart og oversikt over vinregioner. +Forsiden skal også gi tydelig innganger til vinkatalogen, **Find wine by food** og **Wine DNA**. ### Favourites @@ -201,24 +209,21 @@ Popup eller egen side for innlogging og registrering, avhengig av hva som gir be ## Utforming av applikasjonen +Applikasjonen skal kombinere en tradisjonell vinkatalog med mer utforskende funksjonalitet. -Applikasjonen skal gi brukeren to hovedmåter å utforske vin på. +Dersom brukeren vet hva han eller hun leter etter, kan man bruke katalogen og søkefunksjonen direkte. Hvis man derimot er ute etter inspirasjon kan brukeren benytte seg av sidene **Find wine by food** eller **Wine DNA**, i kombinasjon med hjem-siden. -Den første er en vinkatalog med søk, filtrering og sortering. Den andre er geografisk utforskning gjennom et interaktivt kart over vinregioner. +De ulike sidene skal henge sammen. En bruker skal for eksempel kunne oppdage en vin gjennom **Find wine by food**, åpne detaljsiden og deretter bruke **Wine DNA** for å finne lignende viner. -De to delene skal henge sammen. Fra detaljsiden til en vin skal brukeren kunne gå videre til regionen vinen kommer fra, mens en region skal vise aktuelle viner fra området. - -Innloggede brukere skal i tillegg kunne lagre viner som favoritter og finne dem igjen senere. +Vi ønsker at applikasjonen kunne bruke datasettet på ulike måter og gjøre dette på en måte så det fremstår ryddig og enkelt for brukeren. ## Valg av data - - -Dataset: -X-Wines – A Wine Dataset for Recommender Systems and Machine Learning +Dataset: +**X-Wines – A Wine Dataset for Recommender Systems and Machine Learning** https://github.com/rogerioxavier/X-Wines @@ -227,17 +232,25 @@ https://github.com/rogerioxavier/X-Wines Vi planlegger å bruke X-Wines som datagrunnlag for vinkatalogen. -X-Wines er et åpent vindatasett utviklet for blant annet anbefalingssystemer og maskinlæring. Fullversjonen inneholder over 100 000 viner fra 62 land, med informasjon som navn, produsent, vintyper, druer, land, region, årganger, alkoholprosent, fylde og syrenivå. -Datasettet passer godt til prosjektet fordi det inneholder et stort antall produkter og flere egenskaper som kan brukes til søk, filtrering, sortering og detaljvisning. +X-Wines er et åpent vindatasett utviklet for blant annet anbefalingssystemer og maskinlæring. Den inneholder over 100 000 viner fra 62 land, med informasjon som navn, produsent, vintype, druer, land, region, årganger, alkoholprosent, fylde, syrenivå og matmatching. + + -Datasettet inneholder også et separat datasett med brukervurderinger av vinene. Vi vurderer å bruke disse til å vise gjennomsnittlig rating. +Datasettet passer godt til prosjektet fordi det inneholder et stort antall produkter og flere egenskaper som kan brukes til søk, filtrering, sortering, detaljvisning og de utforskende funksjonene. +Matmatching-dataene kan brukes i **Find wine by food**, mens fylde og syrenivå kan brukes i **Explore by taste** som er en funksjon som ligger på hjem-siden. Informasjon om druer, region, vintype, fylde, syre og alkoholprosent kan brukes til å finne lignende viner i **Wine DNA**. + + + + +Vi har også mulighet til å hente ut brukervurderinger av vinene fra datasettet og vurderer å bruke dette for å gi vinene en rating som kan presenteres. + ## Planlagt datamodell @@ -246,37 +259,42 @@ Datasettet inneholder også et separat datasett med brukervurderinger av vinene. En vin kan eksempelvis inneholde: + + ```ts interface Wine { - id: number; - name: string; - winery: string; - type: string; - grapes: string[]; - country: string; - region: string; - vintages: string[]; - alcohol?: number; - body: string; - foodPairings: string[]; - averageRating?: number; + id: number; + name: string; + winery: string; + type: string; + grapes: string[]; + country: string; + region: string; + vintages: string[]; + alcohol?: number; + body: string; + acidity: string; + foodPairings: string[]; + averageRating?: number; } -``` +``` +Det vil også være behov for data knyttet til brukere og favoritter. -Vinregioner kan representeres separat: ```ts -interface Region { - id: number; - name: string; - country: string; - description: string; - latitude?: number; - longitude?: number; -``` +interface User { + id: number; + username: string; + email: string; +} -Det vil også være behov for data knyttet til brukere og favoritter. +interface Favorite { + userId: number; + wineId: number; +} +``` + ## Valg av database og backend @@ -285,7 +303,9 @@ Det vil også være behov for data knyttet til brukere og favoritter. Vi planlegger å bruke PostgreSQL som database. -Dataene våre har flere naturlige relasjoner mellom blant annet viner, regioner, brukere og favoritter. En relasjonsdatabase passer derfor godt til datamodellen. PostgreSQL er et objektrelasjonelt databasesystem som passer fint til vårt prosjekt fordi dataene er tett sammenkoblet og vi ønsker god dataintegritet. PostgreSQL gir også gode muligheter for indeksering og effektive spørringer når vi skal søke, filtrere og sortere i et større datasett. +Dataene våre har flere naturlige relasjoner mellom blant annet viner, brukere og favoritter. En relasjonsdatabase passer derfor godt til datamodellen. PostgreSQL er et objektrelasjonelt databasesystem som passer fint til prosjektet vårt fordi dataene er tett sammenkoblet og vi ønsker god dataintegritet. PostgreSQL gir også gode muligheter for indeksering og effektive spørringer når vi skal søke, filtrere og sortere i et større datasett. + + Backend skal utvikles med Node.js og TypeScript og tilby et GraphQL-API. @@ -294,11 +314,20 @@ Backend skal utvikles med Node.js og TypeScript og tilby et GraphQL-API. Den planlagte arkitekturen er: + + +```text X-Wines CSV -- importskript -- PostgreSQL -- GraphQL-backend -- React-klient + ↓ +Importskript + ↓ +PostgreSQL + ↓ +GraphQL-backend + ↓ +React-klient +``` + ## Foreløpig GraphQL-design @@ -315,33 +344,38 @@ Et foreløpig eksempel på en query kan være: ```graphql type Query { - wines( - search: String -country: String -region: String -grape: String -type: String -body: String -acidity: String -sortBy: String -offset: Int = 0 -limit: Int = 20 -): WinePage! + wines( + search: String + country: String + region: String + grape: String + type: String + body: String + acidity: String + foodPairing: String + sortBy: String + offset: Int = 0 + limit: Int = 20 + ): WinePage! wine(id: ID!): Wine - regions: [Region!]! + similarWines(wineId: ID!, limit: Int = 5): [WineMatch!]! } type WinePage { - items: [Wine!]! - totalCount: Int! + items: [Wine!]! + totalCount: Int! } -``` - +type WineMatch { + wine: Wine! + similarity: Float! + reasons: [String!]! +} +``` @@ -351,15 +385,16 @@ type WinePage { | Del | Valg | Begrunnelse | |---|---|---| | Frontend | React, TypeScript, Vite | Krav i oppgaven | -| Ruting | React Router | Egne URL-er for katalog, detaljside, kart og favoritter | -| Kart | Leaflet med react-leaflet og OpenStreetMap | Åpen kildekode, lett bibliotek, ingen API-nøkkel | +| Ruting | React Router | Egne URL-er for katalog, detaljsider og undersider | +| Visualisering | React-basert visualisering / lett grafbibliotek | Brukes til Explore by taste | | State management | Apollo Client (planlagt) | Cache for GraphQL-svar og lokal state | | Backend | Node.js, TypeScript, Apollo Server (planlagt) | GraphQL er krav i oppgaven, og Apollo Server er godt dokumentert | -| Database | PostgreSQL | Relasjonsdatabase som passer godt til viner, regioner, brukere og favoritter. Støtter også effektiv søking, filtrering og sortering | +| Database | PostgreSQL | Relasjonsdatabase som passer godt til viner, brukere og favoritter. Støtter også effektiv søking, filtrering og sortering | | Testing | Vitest | Vitest er krav i oppgaven | | Kodekvalitet | oxlint og Prettier | Linting og felles formatering | + ## Skalerbarhet @@ -372,7 +407,7 @@ Frontend skal derfor ikke hente hele databasen på én gang. Søk, filtrering og sortering skal håndteres av backend og database, slik at disse operasjonene gjelder hele datasettet og ikke bare data som allerede er lastet inn i klienten. -Klienten skal kun hente den delen av resultatsettet som er nødvendig for visningen. +Klienten skal kun hente den delen av resultatsettet som er nødvendig for visningen.Dette blir relevant fordi selve datasettet består av over 100 000 viner og vi ønsker ikke å hente alt hele tiden. Vi planlegger å bruke enten: @@ -380,6 +415,7 @@ Vi planlegger å bruke enten: - dynamisk lasting av flere resultater + ## Tilgjengelighet @@ -392,9 +428,10 @@ Vi planlegger blant annet å: - bruke labels på skjemaelementer - ha tydelig fokusmarkering - sikre god fargekontrast -- bruke alternativ tekst på relevante bilder -- unngå å bruke farge som eneste måte å formidle informasjon på -- tilby et tilgjengelig alternativ til det interaktive kartet +- bruke alternativ tekst på relevante bilder og illustrasjoner +- tilby en listevisning som alternativ til den visuelle **Explore by taste**-visningen på hjem-siden. +- sørge for at interaktive elementer kan brukes uten mus + ## Bærekraftig webutvikling