diff --git a/README.md b/README.md index 174b7db..923f7a9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# T01-Project-2 +# T01-Project 2 # Wine not? 🍷 @@ -12,6 +12,12 @@ Målet er å lage en oversiktlig og visuelt interessant vinkatalog hvor brukeren --- +## Status: + + +Denne innleveringen består av en spesifikasjon av den planlagte løsningen. Vi beskriver hvilke data applikasjonen skal bruke, hvordan brukergrensesnitt og funksjonaliteten er tenkt utformet og hvordan vi planlegger database, backend og GraphQL-løsning. + + ## Idé @@ -60,9 +66,8 @@ Aktuelle sorteringsmuligheter kan være: - navn -- årgang - rating -- pris +- alkoholprosent Søk, filtrering og sortering skal utføres på hele datasettet gjennom backend, og ikke bare på data som allerede er lastet inn i frontend. @@ -86,11 +91,12 @@ Aktuelle data for en vin er: - region - druetype - vintype -- årgang -- beskrivelse -- bilde +- tilgjengelige årgang +- alkoholprosent +- fylde +- syrenivå +- mat som passer til vinen - rating -- pris Fra detaljsiden skal brukeren også kunne navigere videre til regionen vinen kommer fra. @@ -181,18 +187,59 @@ Interaktivt kart og oversikt over vinregioner. ### Favourites -Oversikt over viner brukeren har lagret som favoritter. +Oversikten over viner brukeren har lagret som favoritter. ### Login / Register -Popup-side for innlogging og registrering. +Popup eller egen side for innlogging og registrering, avhengig av hva som gir best brukeropplevelse. --- +## Utforming av applikasjonen + + +Applikasjonen skal gi brukeren to hovedmåter å utforske vin på. + + +Den første er en vinkatalog med søk, filtrering og sortering. Den andre er geografisk utforskning gjennom et interaktivt kart over vinregioner. + + +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. + + +## Valg av data + + +Dataset: +X-Wines – A Wine Dataset for Recommender Systems and Machine Learning +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. + + +Datasettet inneholder også et separat datasett med brukervurderinger av vinene. Vi vurderer å bruke disse til å vise gjennomsnittlig rating. + + + + + + ## Planlagt datamodell @@ -201,19 +248,22 @@ En vin kan eksempelvis inneholde: ```ts interface Wine { - id: number; - name: string; - producer: string; - vintage: number; - type: string; - grapes: string[]; - country: string; - region: string; - description: string; - imageUrl: string; - rating: number; - price: number; + id: number; + name: string; + winery: string; + type: string; + grapes: string[]; + country: string; + region: string; + vintages: string[]; + alcohol?: number; + body: string; + foodPairings: string[]; + averageRating?: number; } +``` + + Vinregioner kan representeres separat: ```ts interface Region { @@ -221,12 +271,80 @@ interface Region { name: string; country: string; description: string; + latitude?: number; + longitude?: number; ``` Det vil også være behov for data knyttet til brukere og favoritter. +## Valg av database og backend + + +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. + + +Backend skal utvikles med Node.js og TypeScript og tilby et GraphQL-API. + + +Den planlagte arkitekturen er: + + +X-Wines CSV +- importskript +- PostgreSQL +- GraphQL-backend +- React-klient + + +## Foreløpig GraphQL-design + + +GraphQL-backend er ikke implementert ennå, men vi planlegger at frontend skal hente vinene gjennom vår egen backend. + + +Søk, filtrering, sortering og paginering skal utføres i backend slik at funksjonaliteten gjelder hele datasettet og ikke bare vinene som allerede er lastet inn i klienten. + + +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! + + + wine(id: ID!): Wine + regions: [Region!]! +} + + +type WinePage { + items: [Wine!]! + totalCount: Int! +} +``` + + + + + + ## Teknologivalg @@ -237,7 +355,7 @@ Det vil også være behov for data knyttet til brukere og favoritter. | Kart | Leaflet med react-leaflet og OpenStreetMap | Åpen kildekode, lett bibliotek, ingen API-nøkkel | | 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 | Vurderes: PostgreSQL eller MongoDB | Begge støtter indekser for raskt søk og filtrering. Avgjøres før innlevering 2 | +| Database | PostgreSQL | Relasjonsdatabase som passer godt til viner, regioner, 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 | @@ -251,7 +369,7 @@ Et viktig krav i prosjektet er at applikasjonen skal kunne håndtere store datam Frontend skal derfor ikke hente hele databasen på én gang. -Søk, filtrering og sortering skal håndteres av backend og database. +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. @@ -293,21 +411,3 @@ Dette kan blant annet innebære: - optimalisere bilder - unngå unødvendig tunge biblioteker - gjenbruke komponenter - - -## Første underveisinnlevering - - -Denne første underveisinnleveringen består av en spesifikasjon av den planlagte løsningen. - - -Målet er å beskrive: -- hva applikasjonen skal gjøre -- hvilke data systemet skal håndtere -- hvordan brukergrensesnittet er tenkt utformet -- hvordan brukeren skal kunne interagere med applikasjonen -- hvilke teknologier vi planlegger å bruke - - -Implementasjon av database, GraphQL-backend og full funksjonalitet kommer i senere iterasjoner av prosjektet. -