diff --git a/AGENTS.md b/AGENTS.md index dfe5820..518662d 100644 --- a/AGENTS.md +++ b/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`. diff --git a/README.md b/README.md index c35e09c..0558ad5 100644 --- a/README.md +++ b/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.