T28 - Project 2: Search for Countries

Open the deployed app — requires the NTNU network or VPN.

Repository for team IT2810-H26-T28, Project 2.

About the Project

The application allows users to search, filter, and sort through a catalogue of countries around the world, as well as explore detailed information about each country (e.g. capital, continent, languages, population, area, and flag). Users can mark countries as visited or want to visit, with statuses stored persistently on the server.

The project is being developed in stages. The frontend is built with React and TypeScript, and communicates with a GraphQL backend backed by PostgreSQL.

The dataset also includes more than 34,000 cities linked to their respective countries, allowing the application to be tested with a larger dataset.

Status

The project is under active development. The frontend uses Apollo Client to fetch country data from the GraphQL backend, which retrieves data from PostgreSQL. The frontend is served by Apache under /project2/ on the group's NTNU VM, and the backend is managed using systemd.

Users can mark countries as visited or want to visit. The data is stored in the database and linked to an anonymous ID per browser, so no login is required.

Implemented so far:

Country list and country detail page using data fetched from the GraphQL backend.
Responsive CountryQuest landing page with separate search, quiz, and results views, plus navigation to visited, wish-list, and unexplored countries.
Search for countries and cities, with case-insensitive searching performed in the PostgreSQL database.
Debounced search input (300 ms) to reduce unnecessary GraphQL requests.
Backend filtering by continent, language, visited status, and unexplored status, with sorting by name, population, or area.
Country and city pagination handled by the backend; results are loaded in batches of 20.
Users can mark countries as visited or want to visit. Statuses are stored persistently and can be changed or removed.
Quiz attempts are saved in the browser's IndexedDB and can be viewed on the quiz results page.
Loading, error, and empty-result states for searches and data updates.
Apollo Client integration and cache policies for GraphQL queries and paginated results.
Frontend hosted by Apache under /project2/, with PostgreSQL and the GraphQL backend on the same NTNU VM; the backend runs as a systemd service.
Accessibility and sustainable web development: Accessibility testing has covered keyboard navigation, VoiceOver, and Lighthouse. The app uses semantic HTML and ARIA where necessary. We also make conscious choices regarding data usage, caching, and performance to reduce unnecessary resource consumption. See our Accessibility and Sustainability Plan.

User data and anonymous browser ID

The app creates a random ID for each browser and stores it in that browser's local storage. The ID is sent with requests so the backend can associate visited and want-to-visit statuses with the same browser without requiring account creation, passwords, or collecting account details. This keeps the feature simple and avoids introducing a login system for a project that does not need cross-device accounts.

The data is tied to the browser that created it. It is not shared across browsers or devices, and clearing that browser's site data removes the ID needed to look up its saved statuses.

Technology

Frontend: React 19 + TypeScript, set up with Vite
State management: GraphQL client: Apollo Client.
Backend: GraphQL (Node.js/TypeScript)
Database: PostgreSQL, installed directly on the group's VM
Data: countries and cities from open datasets (see Data)
Testing: Vitest and React Testing Library
Linting/formatting: ESLint and Prettier

Architecture and Scalability

The application follows a client-server architecture consisting of three main components:

Frontend: React and TypeScript with Apollo Client for sending GraphQL queries and caching responses.
Backend: Node.js, TypeScript, and Apollo Server, exposing a GraphQL API and handling requests from the frontend.
Database: PostgreSQL, storing structured country and city data.

The backend and database are hosted on the group's NTNU VM. The backend runs as a systemd service to remain available independently of active SSH sessions.

To support larger datasets, searching, filtering, and pagination are handled by the backend and database rather than requiring the frontend to load all records. The GraphQL API allows the frontend to request only the data needed for each view.

The city dataset provides a larger set of records for evaluating database queries and scalability.

For deployment details, see Deployment on the NTNU VM.

Pagination and Caching

Country and city results are fetched in batches of 20 using offset-based pagination. Apollo Client merges the fetched pages into a cached list for each search and filter combination.

Previously fetched results are reused when returning to a search with the same parameters. For example, if 60 countries have been loaded for a search and the user switches to another search before returning, the previously cached results may be displayed immediately.

This is expected Apollo Client cache behavior and helps avoid unnecessary network requests. The cache is not automatically cleared when switching between searches.

Getting Started

Prerequisites

Node.js 24 and npm
Access to the NTNU network or VPN to connect to the deployed backend

To run the frontend using the deployed backend, no direct database access or SSH access to the VM is required.

Start the frontend

npm ci

Connect to the NTNU network or VPN and create a .env.local file in the repository root:

VITE_GRAPHQL_URL=http://it2810-28.idi.ntnu.no:3001/

Start the frontend:

npm run dev

Open http://localhost:5173/project2/ in your browser. The frontend uses the deployed backend, so you do not need database credentials or SSH access to the VM.

To develop the backend locally, see Database Setup for the required database configuration and SSH tunnel instructions.

Deployment (NTNU VM)

Apache serves the production frontend at /project2/ on it2810-28.idi.ntnu.no. The GraphQL backend and PostgreSQL database run on the same VM.

The backend runs as the t28-backend systemd service, allowing it to continue running after SSH logout and start automatically when the VM boots. The browser connects directly to the GraphQL API on port 3001.

The frontend uses base: '/project2/' in vite.config.ts. Build it with the deployed API address:

VITE_GRAPHQL_URL=http://it2810-28.idi.ntnu.no:3001/ npm run build

The API address is embedded at build time. Changing it requires rebuilding and uploading the frontend again.

See Deployment on the NTNU VM for upload instructions, Apache configuration, backend updates, and verification from another machine.

Other Commands

Unless otherwise specified, run these commands from the repository root.

Command	Description
`npm run build`	Type-check and build the frontend for production
`npm run lint`	Run ESLint
`npm run format`	Format code with Prettier
`npm run format:check`	Check formatting without changing files
`npm run preview`	Preview the production build locally
`npm test`	Run frontend component and hook tests (Vitest)
`npm run test:api`	Run GraphQL API tests against the test database
`npm run fetch-data`	Fetch and process country and city data into `data/`
`npm run db:check`	Check the database connection (run from `backend/`)
`npm run db:seed`	Populate the database with country and city data (run from `backend/`)

Testing

Tests use Vitest and React Testing Library. They use fixed test data and require neither the production database nor the NTNU VPN.

Command	What it runs
`npm test`	Component, hook and Apollo cache tests (`src/*/.test.ts(x)`). Use `npm run test:watch` for watch mode.
`npm run test:api`	GraphQL API tests (`backend/test/`). Same as `npm test` run inside `backend/`.

Before running the API tests for the first time, install the backend dependencies with cd backend && npm install.

The API tests run the real resolvers against an in-memory PostgreSQL database (PGlite) that is created and filled with fixed data from backend/test/testDb.ts for each run. Nothing needs to be installed or started.

The tests cover search (case-insensitive), filtering, pagination, totalCount, loading/error/empty states, debounce (300 ms), "Load more" (offset, counter, last page, retry) and Apollo cache behaviour (separate searches, merged pages without duplicates).

When server-side sorting/filtering (#27) and search in both countries and cities (#55) are implemented, extend backend/test/graphql.test.ts and src/lib/apollo.test.ts with sorting tests on the full result set before pagination, and separate country/city results.

The workflow .github/workflows/test.yml runs both test suites on every pull request.

git.ntnu.no has no GitHub-hosted runners, so the workflow runs on a self-hosted runner installed as a service on the group's NTNU VM (it2810-28.idi.ntnu.no). The runner is registered under Settings → Actions → Runners. If jobs are stuck in "Queued", check that the runner is online there, or run sudo ./svc.sh status in the runner folder on the VM.

Data

The dataset is generated by scripts/fetch-data.ts and saved to data/:

data/countries.json: 250 countries
data/cities.json: 34,155 cities with more than 15,000 inhabitants, linked to countries by country code

To fetch the data again, run:

npm run fetch-data

The initial dataset was fetched on 8 October 2026. Country and city data are stored locally in JSON files and imported into PostgreSQL using the database seed script.

Sources and licences

Data	Source	Licence
Countries (name, capital, region, languages, area)	mledoze/countries	ODbL
Population	World Bank	CC BY 4.0
Cities	GeoNames (`cities15000`)	CC BY 4.0
Flags	flagcdn

Notes on the data

Population uses the most recent year available from the World Bank for each country, so the year can differ between countries.
34 countries and territories have no population data at the World Bank (e.g. Taiwan, Vatican City and several small territories). These are shown as Unknown.
Kosovo has different codes in the two sources (UNK in mledoze, XKX in the World Bank). This is handled in the script.
Some territories have no capital (e.g. Antarctica). These are shown as None.
Svalbard and Jan Mayen has no area in the source data. This is shown as Unknown.

Use of AI

We have used AI tools, including Claude Code and ChatGPT, throughout the development of this project, primarily as support for learning, debugging, and solving technical challenges.

Our typical workflow has been to write and implement code ourselves, using AI primarily as a learning tool to explain unfamiliar concepts, identify errors, and suggest improvements rather than generating complete solutions directly.

Examples include working with React and TypeScript, understanding GraphQL queries and resolvers, connecting the frontend to the PostgreSQL database through the backend, and implementing country search with debouncing and appropriate loading and error states.

AI has also been used to help troubleshoot backend deployment on the NTNU VM, configure the systemd service, resolve Git-related issues, and improve technical documentation, including the README.

For the Apache deployment in #22, ChatGPT provided step-by-step deployment guidance, suggested Apache configuration and an HTTP-compatible replacement for crypto.randomUUID(), and drafted deployment documentation. We applied the changes and checked them with ESLint, Prettier, the existing 34 frontend tests, a production build, Apache configuration and HTTP checks, and manual loading of the deployed app.

Using AI to explain concepts and provide feedback on our own code has helped us better understand the technologies used in this project. It has also made debugging and troubleshooting more efficient, particularly when working with unfamiliar tools and configurations.

All AI-generated suggestions have been reviewed and evaluated before being applied, and the group remains responsible for the final implementation.

Project Structure

backend/
├── src/
│   ├── db.ts             # PostgreSQL connection
│   ├── schema.graphql    # GraphQL schema
│   ├── server.ts         # Apollo Server and resolvers
│   ├── seed.ts           # Database seeding
│   └── checkDb.ts        # Database connection check

data/
├── cities.json
└── countries.json

deploy/
├── project2.conf        # Apache configuration for /project2
└── t28-backend.service   # systemd service configuration

docs/
├── backendDeployment.md  # Frontend and backend deployment on NTNU VM
├── databaseSetup.md
├── design.md
└── planAccessibilityAndSustainability.md

scripts/
└── fetch-data.ts

src/
├── components/           # Reusable UI components
├── graphql/              # GraphQL queries
├── hooks/                # Custom React hooks
├── lib/                  # Apollo Client configuration
├── pages/                # Page components
├── types/                # TypeScript types
├── App.tsx
└── main.tsx

Choice of database: PostgreSQL

We chose PostgreSQL because the project's data is structured and relational. Each city belongs to a country, and the database also supports storing user-generated information such as visited countries and countries users want to visit.

A relational database is suitable for this structure because it supports foreign keys, relationships between tables, and efficient queries.

PostgreSQL also supports the project's scalability requirements. Searching, filtering, sorting, and pagination can be performed in the database rather than requiring the frontend to load the entire dataset.

The backend currently supports case-insensitive country searches using ILIKE, as well as filtering and pagination through SQL queries. PostgreSQL also supports indexes and additional optimizations that can improve performance as the dataset grows.

For database configuration instructions, see Database Setup.

Seeding the database

The database is populated using the country and city data stored in data/countries.json and data/cities.json.

The seed script imports this data into PostgreSQL, making it available to the GraphQL backend.

Before running the script, configure the database connection by following the instructions in Database Setup.

Run the following commands from the repository root:

cd backend
npm run db:seed

The seed script can be run multiple times without creating duplicate records. The script also creates the user_country table for user-generated data. Existing rows in user_country are preserved, but the legacy user_country_status table is dropped if it exists. Review the script before reseeding an existing database; see Deployment on the NTNU VM.

Sustainability Measures and Evaluation

To reduce unnecessary data transfer and processing:

Flags use small images (w160) and loading="lazy".
The country list fetches only the fields needed by the country cards. Languages, population, and area are fetched when the detail page is opened.
Search input is debounced by 300 ms. Typing “Norway” quickly resulted in a single search request during manual testing.
Pagination loads 20 countries at a time, and Apollo Client caches results.

Lighthouse

Measured on 28 October 2026 using a local production build (npm run build and npm run preview), with Desktop emulation and Lighthouse 13.3.0.

Metric	Result
Performance	100/100
First Contentful Paint	0.4 s
Largest Contentful Paint	0.4 s
Total Blocking Time	0 ms
Cumulative Layout Shift	0
Speed Index	0.4 s

Lighthouse also reported approximately 96 KiB of unused JavaScript and two reasons preventing back/forward cache restoration. These are potential areas for further improvement. The results reflect local Desktop testing and may vary depending on the device, network, and deployment environment. Lighthouse measures performance, rather than energy consumption directly.

Contributors

Team IT2810-H26-T28

thortve/T28-Project-2

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages