From 42376e6f5536ed25f9b47c7b67b147f0bfe24714 Mon Sep 17 00:00:00 2001 From: Ellen Date: Fri, 16 Oct 2026 22:18:00 +0200 Subject: [PATCH] add README (Close #60) --- Documents/AI_USAGE.md | 8 ++++++ README.md | 57 ++++++++++++++++++++++++++++++------------- 2 files changed, 48 insertions(+), 17 deletions(-) diff --git a/Documents/AI_USAGE.md b/Documents/AI_USAGE.md index e69de29..421c056 100644 --- a/Documents/AI_USAGE.md +++ b/Documents/AI_USAGE.md @@ -0,0 +1,8 @@ +# Bruk av KI + +## Andre innlevering + +KI-verktøy har blitt brukt som støtte gjennom utviklingsprosessen. Det har hovedsakelig blitt brukt til å forklare konsepter innen GraphQL, Apollo Server/Client, PostgreSQL-tilkoblinger (pg pool) og TypeScript-typer, samt til å diskutere hvordan backend-arkitektur og resolver-logikk kan organiseres på en ryddig måte. + +KI har også blitt brukt til å feilsøke Git-mergekonflikter, forklare feilmeldinger og hjelpe med å strukturere SQL-spørringer mot databasen. KI-forslagene har ikke blitt tatt i bruk uten kontroll.Forslag fra KI har blitt gjennomgått, tilpasset prosjektets behov og testet av gruppen før de har blitt tatt i bruk. i har kjørt og testet koden selv, først mot en lokal database og deretter på VM-en, og vi har sjekket resultatet i databasen med egne SQL-spørringer. Valg har blitt tatt av oss. + diff --git a/README.md b/README.md index 53beaa3..9f3919b 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Prosjektet er en fullstack React- og GraphQL-applikasjon som lar brukeren utfors - [Hvor er vi nå](#Hvor-er-vi-nå) - [Frontend](#Frontend) - [Branching-strategi](#Branching-strategi) -- [Bruk av KI](#Bruk-av-KI) + ## Konsept @@ -22,9 +22,18 @@ En katalog for musikkalbum, fysisk mediesamling og utgivelser der brukeren kan s ## Datasett -Bruke et poent datasett fra Kaggle (alternativt MusicBrainz) som datakilde for albumkatalogen. Dataen importes en gang med et eget importskript og lagres i vårt egen database for prosjektet. Applikasjonen kaller da ikke eksterne API-er under kjøring. Filterering, søking og sortering skjer mot vår egen database via GraphQL-backenden. +Dataene kommer fra MusicBrainz sitt åpne API og lagres i vår egen database. Appen kaller aldri eksterne API-er mens den kjører. + +**Kilde**: https://musicbrainz.org/ + +- **Rate limit.** MusicBrainz tillater maks ett kall per sekund per IP, så skriptet venter 1,1 s mellom hvert kall og sender en `User-Agent` med kontaktinfo. Kjøretiden bestemmes av denne grensen. Et søk mot MusicBrainz kan returnere opptil 100 album (maksimum per kall), filtering på søket påvirker importfrekvensen. +- **Utvalg.** Skriptet går gjennom sjanger × tiår og henter album av typen "Album" (uten live/samling). Hver sjanger kan ha flere søketagger (f.eks. `k-pop` og `kpop`). +- **Minimum antall utgaver er et eget valg, ikke en standard.** MusicBrainz har ingen popularitetsdata og filtrerer ikke på antall utgaver av seg selv. Vi har valgt å filtrere på `releases:[N TO *]` fordi album med mange utgaver (reutgivelser, land, formater) som regel er mer kjente og bedre vedlikeholdt, og for å unngå at katalogen fylles av tilfeldige, obskure utgivelser. Terskelen sendes inn som parameter når importen kjøres, og vi har variert den per tiår for å få et bredt utvalg: høy for nyere tiår, der det finnes mange album, og lavere for eldre tiår, der det finnes færre. +- **Skalerbart.** Kvote per sjanger og side-for-side-henting (`offset`) gjør at samme skript kan hente 40 eller 1000 album per sjanger. Det er rate limit som begrenser, ikke koden. For millioner av rader er neste steg MusicBrainz sine datadumper og `COPY`. +- **Robusthet.** Hvert album lagres i en egen transaksjon (album, sjanger og spor lagres sammen eller ikke i det hele tatt). Skriptet prøver på nytt ved 503/429, og hopper over album som allerede finnes, så det kan stoppes og startes på nytt. +- **Covers.** Lastes ned én gang fra Cover Art Archive i 250 px (JPEG) og serveres fra VM-en. Det er bedre for bærekraft og stabilitet enn å hente store bilder fra en ekstern tjeneste for hver bruker. Album uten cover lagres med `cover_path = NULL`, og klienten viser et lite SVG-bilde (`placeholder.svg`). +- **Begrensninger.** Album uten sporliste hoppes over. Bare første plate (`disc 1`) importeres. [Label importeres ikke.] Et album kan ha dukker kun opp under en sjangre. -- Kilde: https://www.kaggle.com/datasets ## Teknologier @@ -41,25 +50,23 @@ Teknologier tatt i bruk ved oppbyggning av applikasjonen: ## Arkitektur og valg -### Backend, GraphQL og Database - For backend og datalagring har vi valgt en løsning basert på Node.js, TypeScript, Apollo Server og PostgreSQL. -1. Apollo Server & GraphQL API +### 1. Apollo Server & GraphQL API Apollo Server (@apollo/server): Vi har satt opp et GraphQL-API med Apollo Server for å gi frontend en fleksibel og typesikker måte å hente akkurat den dataen som trengs. Skjema og typer (schema): GraphQL-skjemaet fungerer som kontrakten mellom frontend og backend. For spor/låter har vi definert duration som et heltall (Int) i millisekunder (i henhold til MusicBrainz-standarden), slik at frontend selv står fritt til å formatere spilletid til lesbart form («MM:SS»). -2. PostgreSQL og Tilkobling (pg) +### 2. PostgreSQL og tilkobling (pg) -Datagrunnlag: Vi benytter PostgreSQL som relasjonsdatabase for å lagre album, artister og spor strukturert. +**Datagrunnlag**: Vi benytter PostgreSQL som relasjonsdatabase for å lagre album, artister og spor strukturert. Installeres direkte på gruppas VM. -Tilkoblingspool (server/src/database/connection.ts): Tilkoblingen håndteres via en gjenbrukbar Pool fra den offisielle pg-pakken. Dette sikrer effektiv ressursbruk og at serveren slipper å opprette nye databasetilkoblinger for hver spørring. +**Tilkoblingspool** (`server/src/database/connection.ts`): Tilkoblingen håndteres via en gjenbrukbar Pool fra den offisielle pg-pakken. Dette sikrer effektiv ressursbruk og at serveren slipper å opprette nye databasetilkoblinger for hver spørring. -Miljøvariabler (.env): Sensitiv informasjon som database-URL, passord og portnumre er isolert i .env-filer for å unngå at hemmeligheter committes til versjonskontroll. +**Miljøvariabler (.env)**: Sensitiv informasjon som database-URL, passord og portnumre er isolert i .env-filer for å unngå at hemmeligheter committes til versjonskontroll. -3. Dynamiske SQL-spørringer i Resolvere +### 3. Dynamiske SQL-spørringer i Resolvere Resolvere (server/src/graphql/resolvers.ts): I stedet for å hente ut alt av data i minnet, bygger resolverne dynamiske SQL-spørringer direkte mot PostgreSQL. @@ -114,6 +121,28 @@ Vi har har prøvd å gjøre grensesnittet enklere å bruke ved at: ### 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. +## 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 + +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. + +Frem til nå har vi testet manuelt: +- Importskriptet er kjørt først mot en lokal database og deretter på VM-en, og resultatet er kontrollert med SQL-spørringer (antall album, sjangerfordeling, album uten spor eller cover). +- GraphQL-spørringene er prøvd i Apollo Sandbox. +- At backend og klient kommuniserer og backend kjører. + +Til neste innlevering planlegger vi blant annet: +- **Komponenttester** med Vitest og Testing Library for sentrale komponenter (søkefelt, albumliste, filter). +- **API-tester** mot GraphQL-backend (søk, filtrering, sortering og paginering). +- **Ende-til-ende-test** av en lengre sekvens (søke, filtrere, åpne et album og legge til en anmeldelse). +- **Databasekontroller** som egen SQL-fil, for eksempel at ingen album mangler spor og at alle album har minst én sjanger. + + ## Branching-strategi Prosjektet følger en feature branch-arbeidsflyt for å holde "main" stabil og reviewbar til enhvertid. @@ -122,9 +151,3 @@ Prosjektet følger en feature branch-arbeidsflyt for å holde "main" stabil og r - For hver oppgave/issue opprettes en egen branch, navngitt med tilhørende issue nummer - Commits på feature-branchen kobles til tilhørende issue på git.ntnu.no, slik at utviklingshistorikken kan spores tilbake til konkrete oppgaver. - Når en oppgave ferdiggjøres, åpnes en pull request fra feature-branchen mot "main". Endringer blir kodegjennomgått av minst ett annet gruppemedlem før den godkjennes og merges. - -## Bruk av KI - -KI-verktøy har blitt brukt som støtte gjennom utviklingsprosessen. Det har hovedsakelig blitt brukt til å forklare konsepter innen GraphQL, Apollo Server/Client, PostgreSQL-tilkoblinger (pg pool) og TypeScript-typer, samt til å diskutere hvordan backend-arkitektur og resolver-logikk kan organiseres på en ryddig måte. - -KI har også blitt brukt til å feilsøke Git-mergekonflikter, forklare feilmeldinger og hjelpe med å strukturere SQL-spørringer mot databasen. Forslag fra KI har blitt gjennomgått, tilpasset prosjektets behov og testet av gruppen før de har blitt tatt i bruk. \ No newline at end of file