diff --git a/README.md b/README.md index 39dc304..cb6a215 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,164 @@ -# T20-Project-2 +# Country Boys – Prosjekt 2 -Repository for team IT2810-H26-T20 in IT2810-H26. +> En søkbar katalog over byer med filtre, sortering, anmeldelser og lokale bokmerker. +> Utviklet i emnet IT2810 Webutvikling ved NTNU. -## Working in this repository +![React](https://img.shields.io/badge/React-20232A?logo=react&logoColor=61DAFB) +![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white) +![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white) +![GraphQL](https://img.shields.io/badge/GraphQL-E10098?logo=graphql&logoColor=white) +![Apollo Server](https://img.shields.io/badge/Apollo_Server-311C87?logo=apollographql&logoColor=white) +![MongoDB](https://img.shields.io/badge/MongoDB-47A248?logo=mongodb&logoColor=white) -`main` is protected — you cannot push to it directly. Work on a branch and -open a pull request: +--- + +## Innhold + +- [Om prosjektet](#om-prosjektet) +- [Teknologistack](#teknologistack) +- [Funksjonalitet](#funksjonalitet) +- [Kom i gang](#kom-i-gang) +- [Database og API](#database-og-api) +- [Arbeidsflyt](#arbeidsflyt) +- [Dokumentasjon](#dokumentasjon) + +--- + +## Om prosjektet + +Country Boys lar brukeren utforske bydata fra gruppas GraphQL-backend. Frontend-en henter data via Apollo Server, som håndterer kommunikasjonen med MongoDB på VM-en. Nettleseren kobler seg aldri direkte til databasen. + +```text +React + TypeScript ──(GraphQL over HTTP)──▶ Apollo Server på VM ──▶ MongoDB på VM + ▲ │ + └──────────── JSON-respons ───────────────┘ +``` + +Under lokal utvikling går frontend-kall til `/api/graphql`. Vite videresender denne ruten til Apollo-serveren på `http://it2810-20.idi.ntnu.no:3001/`. Dette unngår at nettleseren trenger direkte CORS-tilgang til backend mens man utvikler. + +## Teknologistack + +| Lag | Teknologi | Rolle | +|---|---|---| +| **Frontend** | React 19 + TypeScript | Brukergrensesnitt og klienttilstand | +| | Vite 8 | Utviklingsserver, proxy og bygg | +| | Fetch API | Sender GraphQL-operasjoner som HTTP POST; Apollo Client er ikke installert | +| **Backend** | Apollo Server | GraphQL-API på port `3001` | +| **Database** | MongoDB | Lagring på VM, nås av backend | +| **Kvalitet** | TypeScript | Typekontroll ved produksjonsbygg | +| | ESLint | Linting | + +> **Viktig prinsipp:** Søk, filtrering, sortering og paginering sendes til GraphQL-backend. Frontend-en henter bare siden med byer den skal vise. + +## Funksjonalitet + +### Søk og navigering +- [x] Søker på bynavn med case-insensitiv delstrengsmatching via `searchCities`. +- [x] Henter 12 byer om gangen og kan laste inn flere med `offset`-paginering. +- [x] Viser totalt antall treff og om det finnes flere resultater. + +### Filtrering og sortering +- [x] Filtrerer på land. +- [x] Filtrerer på befolkningsintervall. +- [x] Sorterer alfabetisk, etter land eller etter befolkning. +- [ ] Filter- og søkevalg gjenopprettes ikke etter omlasting av siden. + +### Anmeldelser og bokmerker +- [x] Viser byens gjennomsnittsvurdering, antall anmeldelser og eksisterende anmeldelser. +- [x] Sender nye anmeldelser til backend med `addReview`-mutasjonen. +- [x] Lagrer bokmerker i nettleserens `localStorage`. +- [ ] Bokmerker er ikke knyttet til en bruker og synkroniseres ikke mellom enheter. +- [ ] API-et eksponerer ikke innlogging eller brukeradministrasjon. + +### Tilgjengelighet og feiltilstander +- [x] Viser lasting, tomt resultat og API-feil med mulighet for å prøve på nytt. +- [x] Søk, knapper og skjemaelementer har tilgjengelige etiketter og tastaturfokus. + +## Kom i gang + +### Forutsetninger +- Node.js 24 eller nyere. +- pnpm. +- Tilgang til NTNU-nettet eller NTNU-VPN for å nå backend-VM-en. + +### Installasjon og utvikling + +Kjør kommandoene fra prosjektmappen: ```bash -git checkout -b my-feature -git push -u origin my-feature +pnpm install +pnpm dev +``` + +Vite skriver ut lokal URL når serveren starter, vanligvis `http://localhost:5173/`. + +### Scripts + +| Kommando | Beskrivelse | +|---|---| +| `pnpm dev` | Starter Vite-utviklingsserver med GraphQL-proxy | +| `pnpm build` | Kjører TypeScript-kontroll og bygger for produksjon | +| `pnpm lint` | Kjører ESLint | +| `pnpm preview` | Forhåndsviser produksjonsbygget lokalt | + +Det er ikke konfigurert et eget testscript i `package.json` ennå. + +## Database og API + +MongoDB kjører på VM-en og skal bare nås av Apollo-backend. Frontend-en bruker GraphQL-endepunktet: + +```text +http://it2810-20.idi.ntnu.no:3001/ ``` -Before a pull request can be merged: +I utviklingsmodus er Vite-proxyen definert i `vite.config.ts`. Klienten i `src/graphql.ts` bruker `/api/graphql` som standard. En alternativ offentlig GraphQL-adresse kan settes ved bygging med `VITE_GRAPHQL_URL`. + +### GraphQL-operasjoner som frontend bruker + +| Operasjon | Bruk | +|---|---| +| `searchCities` | Søk, land-/befolkningsfilter, sortering og paginering. Backend setter en øvre grense på 100 treff per kall. | +| `countries` | Fyller landfilteret. | +| `addReview` | Lagrer en anmeldelse for en by. | -1. **A member of IT2810-H26-T20 must approve it.** You cannot approve your own pull - request, and approvals from staff do not count — you review each other's - code. -2. **Every review comment must be marked resolved.** Reply to each one, fix it - or explain why not, then click *Resolve conversation*. -3. **Pushing new commits dismisses the approval**, so if you change something - after being approved, ask for another review. This is deliberate: what was - approved is what gets merged. +Test for eksempel følgende spørring i Apollo Sandbox når du er på NTNU-nettet eller VPN: + +```graphql +query { + searchCities(limit: 3, offset: 0) { + totalCount + hasMore + items { + id + name + country + } + } +} +``` - ## Plan for prosjekt 2 +### Sikkerhet og produksjon - Vi planlegger å lage en verdenskatalog for prosjekt 2. Her ønsker vi å gi bruker mulighet til søk etter et bredt utvalg av byer (rundt 30.000-50.000) på verdensbasis. Vi planlegger å gi mulighet for filtrering av land, innbygertall, hovedstad etc. Informasjonen om hver by skal inneholde bynanv, land, innbygertall, m.o.h og potensielt mer informasjon. Vi har også et ønske om å kunne lage et kart hvor du kan trykke deg inn på ulike byer for å få opp informasjon om den gitte byen. - Videre ønsker vi også å gjøre lage et enkelt innlogging/profilsystem, hvor vi gir brukerne mulighet til å gi anmeldelser av de ulike byene som ligger i nettsiden. Her tenker vi både en rangering fra 1-5 stjerner, og mulighet for å skrive en anmeldelse som tekst. +- MongoDB-adresse, brukernavn og passord skal aldri legges i frontend eller sendes til nettleseren. +- Apollo-endepunktet bruker HTTP i dagens VM-oppsett. Dersom frontend publiseres over HTTPS, må webserveren proxy `/api/graphql` til Apollo over backend-nettverket, eller Apollo må tilgjengeliggjøres over HTTPS. +- Hvis produksjonen kaller Apollo direkte fra et annet domene, må backend konfigurere CORS for frontend-domenet. +- API-et har ikke autentisering nå. Anmeldelser sendes med navnet brukeren skriver inn; navnet er ikke verifisert som en identitet. +- API-endepunktet kan kreve NTNU-nett eller VPN. En offentlig frontend blir ikke tilgjengelig for eksterne brukere før nettverkstilgangen til backend er avklart. -## Lenke til datasett -https://www.kaggle.com/datasets/marcobics/world-cities-database?resource=download +## Arbeidsflyt -## Lenke til proof of concept i Figma -https://www.figma.com/design/bSYjp11tbThR76MqKXK67b/Untitled?node-id=1-976&t=EdnBWrcP7BLzqQ6m-1 -Dette er sånn ca. hvordan vi tenker at hovedsiden skal se ut for nettsiden. Mangler noe i dette utkastet, som eksempelvis søkefeltet, men det skal vi ha inn i nettsiden vår. +Gjør endringer i en egen branch og bruk pull request for gjennomgang. + +Før pull request: + +```bash +pnpm lint +pnpm build +``` +## Dokumentasjon +- Denne README-en beskriver funksjoner, teknologistack og hvordan frontend kommuniserer med API-et. +- GraphQL-operasjonene og klientkallet ligger i `src/App.tsx` og `src/graphql.ts`. +- Lokal GraphQL-proxy er definert i `vite.config.ts`. +- Endringer i backend-schemaet må gjenspeiles i GraphQL-operasjonene og TypeScript-typene i frontend. \ No newline at end of file diff --git a/t20-project-2/README.md b/t20-project-2/README.md deleted file mode 100644 index cb6a215..0000000 --- a/t20-project-2/README.md +++ /dev/null @@ -1,164 +0,0 @@ -# Country Boys – Prosjekt 2 - -> En søkbar katalog over byer med filtre, sortering, anmeldelser og lokale bokmerker. -> Utviklet i emnet IT2810 Webutvikling ved NTNU. - -![React](https://img.shields.io/badge/React-20232A?logo=react&logoColor=61DAFB) -![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white) -![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white) -![GraphQL](https://img.shields.io/badge/GraphQL-E10098?logo=graphql&logoColor=white) -![Apollo Server](https://img.shields.io/badge/Apollo_Server-311C87?logo=apollographql&logoColor=white) -![MongoDB](https://img.shields.io/badge/MongoDB-47A248?logo=mongodb&logoColor=white) - ---- - -## Innhold - -- [Om prosjektet](#om-prosjektet) -- [Teknologistack](#teknologistack) -- [Funksjonalitet](#funksjonalitet) -- [Kom i gang](#kom-i-gang) -- [Database og API](#database-og-api) -- [Arbeidsflyt](#arbeidsflyt) -- [Dokumentasjon](#dokumentasjon) - ---- - -## Om prosjektet - -Country Boys lar brukeren utforske bydata fra gruppas GraphQL-backend. Frontend-en henter data via Apollo Server, som håndterer kommunikasjonen med MongoDB på VM-en. Nettleseren kobler seg aldri direkte til databasen. - -```text -React + TypeScript ──(GraphQL over HTTP)──▶ Apollo Server på VM ──▶ MongoDB på VM - ▲ │ - └──────────── JSON-respons ───────────────┘ -``` - -Under lokal utvikling går frontend-kall til `/api/graphql`. Vite videresender denne ruten til Apollo-serveren på `http://it2810-20.idi.ntnu.no:3001/`. Dette unngår at nettleseren trenger direkte CORS-tilgang til backend mens man utvikler. - -## Teknologistack - -| Lag | Teknologi | Rolle | -|---|---|---| -| **Frontend** | React 19 + TypeScript | Brukergrensesnitt og klienttilstand | -| | Vite 8 | Utviklingsserver, proxy og bygg | -| | Fetch API | Sender GraphQL-operasjoner som HTTP POST; Apollo Client er ikke installert | -| **Backend** | Apollo Server | GraphQL-API på port `3001` | -| **Database** | MongoDB | Lagring på VM, nås av backend | -| **Kvalitet** | TypeScript | Typekontroll ved produksjonsbygg | -| | ESLint | Linting | - -> **Viktig prinsipp:** Søk, filtrering, sortering og paginering sendes til GraphQL-backend. Frontend-en henter bare siden med byer den skal vise. - -## Funksjonalitet - -### Søk og navigering -- [x] Søker på bynavn med case-insensitiv delstrengsmatching via `searchCities`. -- [x] Henter 12 byer om gangen og kan laste inn flere med `offset`-paginering. -- [x] Viser totalt antall treff og om det finnes flere resultater. - -### Filtrering og sortering -- [x] Filtrerer på land. -- [x] Filtrerer på befolkningsintervall. -- [x] Sorterer alfabetisk, etter land eller etter befolkning. -- [ ] Filter- og søkevalg gjenopprettes ikke etter omlasting av siden. - -### Anmeldelser og bokmerker -- [x] Viser byens gjennomsnittsvurdering, antall anmeldelser og eksisterende anmeldelser. -- [x] Sender nye anmeldelser til backend med `addReview`-mutasjonen. -- [x] Lagrer bokmerker i nettleserens `localStorage`. -- [ ] Bokmerker er ikke knyttet til en bruker og synkroniseres ikke mellom enheter. -- [ ] API-et eksponerer ikke innlogging eller brukeradministrasjon. - -### Tilgjengelighet og feiltilstander -- [x] Viser lasting, tomt resultat og API-feil med mulighet for å prøve på nytt. -- [x] Søk, knapper og skjemaelementer har tilgjengelige etiketter og tastaturfokus. - -## Kom i gang - -### Forutsetninger -- Node.js 24 eller nyere. -- pnpm. -- Tilgang til NTNU-nettet eller NTNU-VPN for å nå backend-VM-en. - -### Installasjon og utvikling - -Kjør kommandoene fra prosjektmappen: - -```bash -pnpm install -pnpm dev -``` - -Vite skriver ut lokal URL når serveren starter, vanligvis `http://localhost:5173/`. - -### Scripts - -| Kommando | Beskrivelse | -|---|---| -| `pnpm dev` | Starter Vite-utviklingsserver med GraphQL-proxy | -| `pnpm build` | Kjører TypeScript-kontroll og bygger for produksjon | -| `pnpm lint` | Kjører ESLint | -| `pnpm preview` | Forhåndsviser produksjonsbygget lokalt | - -Det er ikke konfigurert et eget testscript i `package.json` ennå. - -## Database og API - -MongoDB kjører på VM-en og skal bare nås av Apollo-backend. Frontend-en bruker GraphQL-endepunktet: - -```text -http://it2810-20.idi.ntnu.no:3001/ -``` - -I utviklingsmodus er Vite-proxyen definert i `vite.config.ts`. Klienten i `src/graphql.ts` bruker `/api/graphql` som standard. En alternativ offentlig GraphQL-adresse kan settes ved bygging med `VITE_GRAPHQL_URL`. - -### GraphQL-operasjoner som frontend bruker - -| Operasjon | Bruk | -|---|---| -| `searchCities` | Søk, land-/befolkningsfilter, sortering og paginering. Backend setter en øvre grense på 100 treff per kall. | -| `countries` | Fyller landfilteret. | -| `addReview` | Lagrer en anmeldelse for en by. | - -Test for eksempel følgende spørring i Apollo Sandbox når du er på NTNU-nettet eller VPN: - -```graphql -query { - searchCities(limit: 3, offset: 0) { - totalCount - hasMore - items { - id - name - country - } - } -} -``` - -### Sikkerhet og produksjon - -- MongoDB-adresse, brukernavn og passord skal aldri legges i frontend eller sendes til nettleseren. -- Apollo-endepunktet bruker HTTP i dagens VM-oppsett. Dersom frontend publiseres over HTTPS, må webserveren proxy `/api/graphql` til Apollo over backend-nettverket, eller Apollo må tilgjengeliggjøres over HTTPS. -- Hvis produksjonen kaller Apollo direkte fra et annet domene, må backend konfigurere CORS for frontend-domenet. -- API-et har ikke autentisering nå. Anmeldelser sendes med navnet brukeren skriver inn; navnet er ikke verifisert som en identitet. -- API-endepunktet kan kreve NTNU-nett eller VPN. En offentlig frontend blir ikke tilgjengelig for eksterne brukere før nettverkstilgangen til backend er avklart. - -## Arbeidsflyt - -Gjør endringer i en egen branch og bruk pull request for gjennomgang. - -Før pull request: - -```bash -pnpm lint -pnpm build -``` - -## Dokumentasjon - -- Denne README-en beskriver funksjoner, teknologistack og hvordan frontend kommuniserer med API-et. -- GraphQL-operasjonene og klientkallet ligger i `src/App.tsx` og `src/graphql.ts`. -- Lokal GraphQL-proxy er definert i `vite.config.ts`. -- Endringer i backend-schemaet må gjenspeiles i GraphQL-operasjonene og TypeScript-typene i frontend. \ No newline at end of file