diff --git a/Documents/TIME_USAGE.md b/Documents/TIME_USAGE.md index 44f03a2..0069b06 100644 --- a/Documents/TIME_USAGE.md +++ b/Documents/TIME_USAGE.md @@ -2,4 +2,5 @@ Denne siden inneholder tiden som gruppa brukte på prosjektet. Dette inkluderer når vi møttes, hvem som var til stede, og hvor lenge vi satt. ## Torsdag 1. oktober -Alle fire gruppemedlemmer møtte opp. Vi jobbet fra 9:30 og frem til 15:30. Med andre ord, jobbet vi med prosjektet i seks timer. \ No newline at end of file +Alle fire gruppemedlemmer møtte opp. Vi jobbet fra 9:30 og frem til 15:30. Med andre ord, jobbet vi med prosjektet i seks timer. + diff --git a/README.md b/README.md index 5fa58c5..23c003a 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,14 @@ Prosjektet er en fullstack React- og GraphQL-applikasjon som lar brukeren utfors ## Innholdsfortegnelse -- [Konsept](#Konsept) -- [Datasett](#Datasett) -- [Teknologier](#Teknologier) -- [Kom i gang](#Kom-i-gang) -- [Arkitektur og valg](#Arkitektur-og-valg) +- [Konsept](#konsept) +- [Datasett](#datasett) +- [Teknologier](#teknologier) +- [Kom i gang](#kom-i-gang) +- [Arkitektur og valg](#arkitektur-og-valg) - [VM og deployment](#vm-og-deployment) -- [Hvor er vi nå](#Hvor-er-vi-nå) -- [Frontend](#Frontend) -- [Branching-strategi](#Branching-strategi) +- [Hvor vi er nå](#hvor-vi-er-nå) +- [Branching-strategi](#branching-strategi) ## Konsept @@ -49,6 +48,64 @@ Teknologier tatt i bruk ved oppbyggning av applikasjonen: ## Kom i gang +### Forutsetninger + +- [Node.js](https://nodejs.org/) 22.12 eller nyere. +- [pnpm](https://pnpm.io/installation), som kan aktiveres med `corepack enable` hvis Corepack følger med Node.js-installasjonen. +- Tilgang til en PostgreSQL-database med prosjektets data. Be prosjektgruppen om en database-URL eller oppsett for en lokal database; tilkoblingsdetaljer og data ligger ikke i repoet. + +Åpne repoets rotmappe i VS Code. Installer avhengighetene i to omganger, siden frontend og backend har hver sin `package.json`: + +```bash +# Fra repoets rotmappe +pnpm install + +# Installer backend-avhengighetene +cd server +pnpm install +cd .. +``` + +### Konfigurer miljøvariabler + +Opprett `.env.local` i repoets rotmappe for frontend: + +```env +VITE_API_URL=http://localhost:3001/ +``` + +Opprett `server/.env` for backend, og bruk database-URL-en dere har fått: + +```env +PORT=3001 +DATABASE_URL=postgresql://BRUKER:PASSORD@HOST:5432/DATABASENAVN +``` + +Ikke legg ekte passord eller andre hemmeligheter i Git. Hvis databasen er ny og tom, må skjemaet opprettes før oppstart. Kjør kommandoen fra `server`-mappen i PowerShell: + +```powershell +psql $env:DATABASE_URL -f .\src\database\migrations\schema.sql +``` + +Skjemaet inneholder ikke albumdata; bruk en database som allerede er fylt med data, eller følg gruppens instruksjoner for import. + +### Start appen + +Start backend og frontend i hver sin VS Code-terminal. Kjør backend fra `server`-mappen: + +```bash +cd server +pnpm dev +``` + +Kjør frontend fra repoets rotmappe i den andre terminalen: + +```bash +pnpm dev +``` + +Åpne adressen Vite viser i terminalen, vanligvis . Coverbilder hentes via Vite-proxyen fra prosjektets VM, så du trenger nettverkstilgang til den for å se disse. + ## Arkitektur og valg For backend og datalagring har vi valgt en løsning basert på Node.js, TypeScript, Apollo Server og PostgreSQL. @@ -166,40 +223,46 @@ pm2 restart cdllection-backend Kun én backendprosess skal bruke port 3001. Det skal derfor ikke startes en ekstra backendprosess manuelt på VM-en mens cdllection-backend allerede kjører gjennom PM2. -# Hvor vi er nå +## Hvor vi er nå -## Frontend +### Frontend Hovedfokuset har vært på katalogvisningen og hvordan brukeren kan utforske albumene. Målet har vært å lage et oversiktlig og brukervennlig grensesnitt der brukeren kan bla gjennom, søke etter artister eller albumtitler, filtrere resultatene og åpne et spesifikt album for mer detaljert informasjon. Vi har delt brukergrensesnittet inn i mindre komponenter for å gjøre koden mer oversiktlig og enklere å vedlikeholde. Katalogsiden håndterer søk, filtrering og paginering, mens egne komponenter brukes til albumvisning, søkefelt, filtre og detaljvisning. Vi har også jobbet med design og tilgjengelighet, blant annet visuell utforming og synlig fokus ved tastaturnavigasjon på katalogsiden. -### Katalogvisning +**Katalogvisning** + Fil: CataloguePage Katalogsiden er hovedsiden for å utforske album. Den henter albumdata fra GraphQL-backenden og viser resultatene i grensesnittet. Siden inneholder oversikt over søketekst, valgte filtre, gjeldende side og om filterpanelet er synlig. Reacts 'useState' brukes til å lagre og oppdatere denne tilstanden. Når brukeren endrer søket eller filtrene, sendes en ny forespørsel til backenden og visningen oppdateres med de nye resultatene. -### Søk +**Søk** + Fil: SearchBar Søkefeltet lar brukeren søke etter album basert på tittel eller artist. Søket er ikke avhengig av store eller små bokstaver, slik at f.eks. "Radiohead" og "radiohead" gir tilsvarende søkeresultater. Søketeksten lagres i tilstanden til katalogsiden. For å unngå å sende unødvendig mange GraphQL-forespørsler for hvert tastetrykk, brukes debounce før søket sendes til backenden. Selve søket utføres dermed mot hele datasettet i databasen, og ikke bare på albumene som allerede er lastet inn i frontend. -### Filtrering +**Filtrering** + Fil: FilterControls Filterkomponenten lar brukeren avgrense albumene etter sjanger og tiår. Filtrene kombineres med søket, slik at resultatsiden bare viser album som oppfyller de aktive kriteriene. Filtreringen utføres i databasen slik at hele datasettet tas med i resultatet. Det er også mulig å fjerne filtrene for å gå tilbake til en bredere visning av katalogen. I tillegg til det kan filterpanelet skjules for å gi mer plass til albumene. Det er også klargjort design for filtrering etter brukervurdering, men funksjonaliteten implementeres senere når brukerdata er på plass. -### Albumkort og Albumliste +**Albumkort og Albumliste** + Fil: AlbumList og AlbumCard AlbumList mottar en liste med album og viser et albumkort for hvert album. AlbumCard håndterer presentasjonen av det enkelte albumet, blant annet tittel, utgivelsesår og coverbilde. Dersom et album ikke har en tilgjengelig coveradresse, viser grensesnittet en plassholder i stedet. Dette gjør at albumkortene fortsatt har en visuell representasjon selv når coverbildet mangler. -### Paginering +**Paginering** + Katalogen bruker backend-paginering for å dele resultatet inn i mindre sider, slik at frontend ikke trenger å hente hele albumkatalogen på én gang. Antallet album per side bestemmes av om filterpanelet er synlig. Frontend sender 'first' og 'after' gjennom GraphQL-spørringen. 'first' bestemmer hvor mange album som skal hentes, mens 'after' brukes som offset for hvor neste del av resultatsettet skal starte. GraphQL-responsen inneholder også 'totalCount', 'endCursor' og 'hasNextPage', som frontend bruker til å styre navigasjonen mellom sidene. Brukeren kan navigere mellom sidene ved hjelp av forrige- og neste-knappene. Knappene deaktiveres når brukeren er på den første eller siste siden. Gjeldende sidetall og totalt antall sider vises også. Når søket eller filtrene endres, tilbakestilles pagineringen til første side, slik at brukeren ikke blir stående på en side som ikke lenger finnes. -### Navigasjon og albumdetaljer +**Navigasjon og albumdetaljer** + Filer: App.tsx og AlbumDetailPage.tsx Applikasjonen bruker React Router til å navigere mellom katalogsiden og detaljsiden for et album. Katalogen ligger på /, mens albumdetaljer vises gjennom en rute på formen: @@ -209,29 +272,32 @@ Applikasjonen bruker React Router til å navigere mellom katalogsiden og detaljs Når brukeren åpner et album, brukes albumets ID til å hente informasjon om det aktuelle albumet gjennom GraphQL. Dette gjør det mulig å åpne en egen side for et valgt album uten å samle all funksjonaliteten i én komponent. -### Loading og feiltilstander +**Loading og feiltilstander** + Apollo Client brukes til å håndtere loading- og error-tilstander når frontend kommuniserer med GraphQL-backenden. Dette gjør at brukeren får tilbakemelding mens data lastes, og at frontend kan vise en feilmelding dersom forespørselen til backenden ikke kan gjennomføres. -### Tilgjengelighet +***Tilgjengelighet** + Vi har prøvd å gjøre grensesnittet enklere å bruke ved at: - Skjemafeltet har tilknyttede etiketter, slik at det er tydelig hva brukeren skal skrive inn eller velge. - Interaktive elementer har synlig fokus ved tastaturnavigasjon. - Og at hvis søket og filtrene ikke gir noen treff, vises en melding som informerer brukeren om at ingen album ble funnet, med forslag om å endre søket eller filtrene. Tilgjengelighet er foreløpig hovedsakelig implementert på katalogsiden. Albumdetaljsiden skal videreutvikles i neste innlevering. -### Design og styling +**Design og styling** + Stylingen er implementert med CSS. Vi har brukt en spesifikk fargepalett og fontene Clash Display og Archivo for å skape et tydelig visuelt hierarki mellom overskrifter og vanlig tekst. Layouten bruker blant annet CSS Grid og Flexbox for å organisere albumkort og grensesnittelementer. Design og layout skal videreutvikles i neste innlevering, spesielt på albumdetaljsiden. -## Database +### Database PostgreSQL kjører på VM-en med egen databasebruker med begrensede rettigheter, og passord ligger i `.env` (ikke i git). Skjemaet (`schema.sql`) er på plass med tabeller for album, sjangre, spor, anmeldelser og samlinger, samt indekser for søk, sortering og filtrering (trigram-indekser, nøkkelindekser for cursor-paginering og tiårsfilter). Databasen er fylt med ca. 5000 album via importskriptet, som er kjørt på VM-en. Importen kan gjentas og utvides med flere tiår og høyere kvoter. Covers er lastet ned lokalt i 250 px, og covers med `cover_path = NULL` vises med plassholder i klienten. Brukere, anmeldelser og samlinger skal bygges ut sammen med innlogging. Tabellene finnes i skjemaet, men lagrer foreløpig bare et brukernavn som tekst, og mangler kobling til backend og klient. -## Tester +### Tester Per andre underveisinnlevering har vi ikke kommet i gang med automatiske tester. Fokus så langt har vært å få database, backend og klient til å fungere sammen.