Docs: write project specification in README

AGENTS.md

@@ -3,19 +3,21 @@
 
 - **Name:** UFOund it
 - **What it is:** UFOund it, is a webapp that displays UFO sightings.
-- **Dataset:** CSV file, approx 15mb.
+- **Dataset:** [NUFORC UFO Sightings (Kaggle)](https://www.kaggle.com/datasets/NUFORC/ufo-sightings), CSV, approx 80,000 reports, approx 15mb.
+- **Current state:** The frontend runs on hand-written mock data in `frontend/src/data/`. No backend or database yet.
 - **Course context:** NTNU IT2810 project. Must be reproducible, accessible and sustainable.
 
 ## Tech stack
 
 | Area | Choice |
 | --- | --- |
-| Frontend | React, TypeScript, Vite |
-| API | GraphQL (custom backend, Node + TypeScript)
-| GraphQL client | Apollo Client
-| Testing | Vitest (components), e2e tool, API testing |
+| Frontend | React, TypeScript, Vite, React Router |
+| API | GraphQL (custom backend, Node + TypeScript, Apollo Server) |
+| GraphQL client | Apollo Client |
+| Database | MySQL (leaning, not final), run directly on the VM |
+| Testing | Vitest + React Testing Library (components), e2e tool and API testing TBD |
 | Linting / formatting | ESLint, Prettier |
-| UI libraries | Leaflet with react-leaflet. |
+| UI libraries | Leaflet with react-leaflet (OpenStreetMap tiles, no API key) |
 
 ## Commands
 
@@ -29,35 +31,37 @@ npm install
 npm run dev
 
 # Start backend
-TODO
+# TODO: backend not created yet
 
-# Build
-TODO
+# Build (type-check + production build of the frontend)
+npm run build
 
 # Lint
-npm lint
+npm run lint
 
 # Format
 npm run format:check
 
-# Run unit/component tests
-TODO
+# Run unit/component tests (Vitest, watch mode)
+npm run test
 
 # Run end-to-end tests
-TODO
+# TODO: e2e tool not chosen yet
 ```
 
 ## Folder structure
 
 ```
-TODO
-# frontend/
-#   src/
-#     components/
-#     pages/
-#     graphql/
-#     store/
-# backend/
+frontend/
+  src/
+    components/   Reusable UI (Banner, SearchBar, SightingList, SightingMap)
+    pages/        Route-level components (SearchPage, SightingDetailPage)
+    hooks/        Custom hooks (debounce, sighting search, single sighting)
+    utils/        Pure helpers (filtering, formatting)
+    types/        Shared TypeScript types
+    data/         Mock sightings (to be replaced by GraphQL)
+    # graphql/    Planned: Apollo queries
+# backend/        Planned: Node + TypeScript GraphQL server
 #   src/
 #     schema/
 #     resolvers/
@@ -86,7 +90,7 @@ TODO
 - Optimize and lazy-load images.
 - Avoid unnecessary network requests (debounce search, paginate or scroll-load results).
 - Sort and filter on the server so the client only loads what it shows.
-- 
+
 ## Git and workflow
 
 - Work on feature branches. Never push directly to `main`.

README.md

@@ -2,6 +2,33 @@
 
 Repository for team IT2810-H26-T25 in IT2810-H26.
 
+## Contents
+
+1. [Running the Project](#running-the-project)
+2. [Working in this repository](#working-in-this-repository)
+3. [Project Description](#project-description)
+4. [Planned Functionality](#planned-functionality)
+5. [Stored User-Generated Data](#stored-user-generated-data)
+6. [Technology Choices](#technology-choices)
+7. [AI Usage](#ai-usage)
+
+## Running the Project
+
+To get a feel for how the application will look, you can run the project
+locally. You need [Node.js](https://nodejs.org/) and npm installed. From the
+repository root:
+
+```bash
+npm install
+npm run dev
+```
+
+Then open the address Vite prints in the terminal, usually
+http://localhost:5173. For this first submission there is no backend or
+database to set up, because the app runs on example data stored in the
+frontend. Other useful commands are `npm run build`, `npm run lint` and
+`npm run test`.
+
 ## Working in this repository
 
 `main` is protected — you cannot push to it directly. Work on a branch and
@@ -24,34 +51,111 @@ Before a pull request can be merged:
    approved is what gets merged.
 
 ## Project Description
-The project is about observed UFO sightings.
-Our group found an interesting dataset about observed UFO sightings which is about 80k observations.
-This infromation is used to create an application which allows to perform search, and view the infromation about any UFO sighting.
-Described further in planned functionality.
-
-## Planned Functionality 
-The planned functionality is following:
-
-Landing page with one 'Daily' chosen UFO sighting.
-The page does display information about the UFO sighting with a map of the location of observation.
-Performed search to find UFO sightings.
-The user can create a UFO sighting.
-For future:
-Maybe create an option for comments or up-votes on a UFO sighting.
 
+UFOund it is a web application for exploring reported UFO sightings. You can
+see where people have observed UFOs, what the objects looked like and what the
+observers wrote about them.
+
+The data comes from the
+[UFO Sightings dataset on Kaggle](https://www.kaggle.com/datasets/NUFORC/ufo-sightings),
+which contains about 80,000 reports collected by the National UFO Reporting
+Center (NUFORC). Each report has a date and time, city, state, country, the
+shape of the object, how long the sighting lasted, a free text comment from the
+observer, the date it was posted and the latitude and longitude of the
+location.
+
+We chose this topic because it is fun and a little unusual, and because the
+dataset suits the requirements of the project well. The coordinates let us show
+every sighting on a map, the comments give us real text to search in, and the
+shapes and dates are natural things to sort and filter on. With 80,000 rows the
+dataset is also large enough that searching, sorting and paging have to happen
+on the server, which is what the course asks for.
+
+For this first submission the application runs on a small set of hand written
+example sightings stored in the frontend. There is no backend or database yet.
+
+## Planned Functionality
+
+**Featured sighting.** The landing page shows a featured sighting of the day
+with its location on a map, its shape and the observer's comment.
+
+**Search.** A search field finds sightings by city, shape or words in the
+comment. The search is case insensitive and waits until the user stops typing
+before it runs, so it does not send a request for every keystroke. This already
+works on the example data.
+
+**List view.** Search results are shown as a list where each sighting has a
+small map, the location, date, shape, duration and comment. Clicking anywhere on
+a sighting opens its detail page. Since a search can match thousands of
+sightings, the list will either be split into pages or load more results as the
+user scrolls. We have not decided which yet.
+
+**Detail view.** Each sighting has its own page with a larger map that can be
+dragged and zoomed, along with all the information about the report. The page
+has its own URL, so a sighting can be shared or bookmarked.
+
+**Sorting and filtering.** Results can be sorted by newest or oldest first, or
+alphabetically by city or shape. The search and sort choices are kept in the
+URL, so they are still there when the user returns from a detail page or
+refreshes.
+
+**Adding sightings.** Users will be able to report their own sightings, which
+are then stored in the database and shown alongside the ones from the dataset.
+
+Right now the search, sorting and filtering run in the browser on the example
+data, so we can try out how it feels. In the finished version this will be
+replaced by GraphQL queries against the backend, so that sorting and filtering
+always cover the whole dataset and not only what has been loaded in the
+browser.
 
 ## Stored User-Generated Data
-Created UFO sightings.
-TODO
 
+The main data users create are their own sighting reports. A report will have
+the same fields as the sightings in the dataset, which means location, date and
+time, shape, duration and a comment. These are stored permanently in the
+database.
 
-## Outline Technology Choices
-TODO
+We have not yet decided whether users will log in. Without accounts, reports
+are stored without being tied to a user. With accounts, users could see and
+manage their own reports, and we could later add comments or up votes on
+sightings, which is an idea we would like to explore if there is time.
 
+## Technology Choices
 
-## AI Usage
-TODO
+The frontend is built with React, TypeScript and Vite. React Router handles
+navigation between the search page and the detail pages. Maps are made with
+Leaflet through react-leaflet, using map tiles from OpenStreetMap, which is free
+and needs no API key.
 
+The backend will be a Node.js server written in TypeScript with a GraphQL API.
+We plan to use Apollo Server on the backend and Apollo Client in the frontend,
+since Apollo is well documented and handles caching of query results for us.
+For the database we are leaning towards MySQL, but this is not final. The
+backend and database will run directly on the course virtual machine, without
+Docker.
 
+We will test components with Vitest and React Testing Library, and add end to
+end tests and API tests as the application grows. ESLint and Prettier keep the
+code consistent, and every pull request is reviewed by another group member
+before it is merged into main.
 
+## AI Usage
 
+We use AI coding assistants, mainly Claude Code, to generate code, fix bugs and
+quality check what we have written. We treat the output as a suggestion and not
+as finished work. Everything the AI produces is read through and understood by
+the person who uses it before it is committed, and we change or rewrite it when
+it does not fit the project.
+
+AI generated code goes through the same checks as the rest of our code. We run
+lint, Prettier and the build before committing, and every pull request is
+reviewed manually by another group member before it is merged into main. When
+AI has contributed to a change, the pull request description says which tool
+was used and what it helped with.
+
+The repository contains an AGENTS.md file that describes our tech stack, code
+style, accessibility requirements and git workflow. AI tools read this file, so
+their suggestions follow the same conventions as the rest of the group.
+Decisions about architecture and scope, such as which libraries to add and
+which features belong in which issue, are made by the group and not left to the
+AI.