From 295b325d01390da3a1325ac51b66d817cd1fb758 Mon Sep 17 00:00:00 2001 From: mina Date: Fri, 30 Oct 2026 03:35:44 +0100 Subject: [PATCH] docs: update readme for delivery 3 --- README.md | 221 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 166 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index a7ed400..3f4f2cc 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,126 @@ ## Virtual machine -The webpage can be accessed through the group’s virtual machine at: +The application is available on the group's virtual machine at: -- http://it2810-12.idi.ntnu.no/project2/ +http://it2810-12.idi.ntnu.no/project2/ -The project uses a MongoDB database hosted on the group’s virtual machine. The GraphQL backend is configured to run on port `3001`. +The MongoDB database and GraphQL backend are hosted directly on the virtual machine. + +The backend is configured to run on port `3001`. ## Overview -Artex is a searchable artwork catalogue developed as part of IT2810. The application allows users to explore artwork stored in our own database through a React frontend and a GraphQL backend. +Artex is a searchable artwork catalogue developed as part of IT2810 Web Development at NTNU. + +The application allows users to explore artworks from the Metropolitan Museum of Art collection through a React frontend connected to our own GraphQL backend and MongoDB database. + +Users can search, filter and sort the artwork catalogue, browse results using pagination and open individual artworks to view additional information. Users can also create an account, log in, create personal galleries and add artworks to their galleries. User-generated gallery data is stored persistently in the database. + +For the third delivery, the project represents a first complete prototype of the application, with particular focus on catalogue functionality, frontend/backend integration, accessibility and sustainable web development. + +## Main functionality + +The application currently supports: + +- Searching artworks by title or artist +- Case-insensitive search +- Search submission through a search button to avoid unnecessary requests +- Artist filtering with debounced artist search +- Sorting by title, artist and year +- Server-side filtering and sorting +- Pagination of artwork results +- Individual artwork detail pages +- Responsive layouts for different screen sizes +- User registration and login +- Protected profile pages for authenticated users +- Creation of personal galleries +- Adding artworks to galleries +- Persistent user-generated gallery data +- Profile and cover image customization +- Loading, empty and error states for relevant functionality + +Sorting, filtering and pagination are performed through the backend rather than only on the data currently loaded in the browser. This allows the solution to scale to larger datasets. + +## Technologies + +### Frontend + +- React +- TypeScript +- Vite +- Tailwind CSS +- React Router +- Zustand +- React Select +- Lucide React + +### Backend + +- Node.js +- TypeScript +- GraphQL +- Apollo Server +- MongoDB + +### Development tools + +- ESLint +- Prettier +- Git +- GitLab + +## Technical choices + +The project is divided into a frontend, backend and database. The frontend is built with React and TypeScript using Vite, while the backend is built with Node.js, TypeScript, GraphQL and Apollo Server. MongoDB is used to store artwork data, users and galleries. + +The frontend communicates with the backend through GraphQL. This allows the client to request only the fields it needs and makes it possible to perform pagination, search, filtering and sorting on the backend instead of loading the complete dataset into the browser. + +Artwork results are loaded using pagination. The frontend sends a `limit` and `offset` to the GraphQL backend, and the backend retrieves only the requested portion of the dataset from MongoDB. The catalogue currently displays 12 artworks per page. This approach was chosen with scalability in mind, since the application should be able to handle a significantly larger dataset without transferring all artwork data to the client at once. + +Filtering and sorting are also performed by the backend so that they apply to the complete result set rather than only the artworks currently displayed in the browser. The application supports sorting by title, artist and year in ascending or descending order. + +The main artwork search is submitted explicitly instead of sending a request for every character typed into the search field. Artist search uses a debounce before requesting matching artists from the backend. These choices reduce unnecessary network requests while still providing a responsive user experience. + +Zustand is used for shared frontend state. Authentication state, including the current user and authentication token, is stored in a central Zustand store and shared across login, registration, protected routes, profile navigation and authenticated gallery functionality. The store is persisted using `sessionStorage`, allowing the user to remain logged in when refreshing the page during the same browser session. + +State that only belongs to a single component remains managed using React state. Form input, modal visibility, loading states and locally fetched gallery data are therefore kept local instead of being moved into global state unnecessarily. + +Artex also includes persistent user-generated data through personal galleries. Authenticated users can create galleries and add artworks to them. Gallery information and artwork IDs are stored in MongoDB, so the data remains available after refreshing or logging in again. When an artwork is added to a gallery, set-based database updates are used to avoid storing the same artwork multiple times in the same gallery. + +The design is based on our Figma prototype and is implemented responsively so that the layout adapts to different screen sizes. The frontend is divided into reusable components and hooks to separate responsibilities and make the code easier to maintain and test. + +## Accessibility + +Accessibility has been considered throughout the frontend implementation. + +Examples of accessibility choices include semantic HTML elements such as `main`, `section`, `form`, `button` and links, labels connected to form inputs, `aria-label` for icon-only controls and accessible attributes for expandable filters and dialogs. + +The catalogue search uses `role="search"`, while relevant feedback is presented using `role="alert"` and `role="status"`. Meaningful images use alternative text, while decorative images use empty alternative text where appropriate. Interactive elements use keyboard-accessible buttons and links, and visible focus styles are included for relevant controls. + +The application also provides loading states, empty-result messages and error feedback so that users receive clear information about what is happening. + +Accessibility will continue to be reviewed throughout the remaining development process, particularly keyboard navigation, focus handling in dialogs and general usability. -The application is based on artwork data from the Metropolitan Museum of Art collection. Artwork information is stored in a MongoDB database and accessed through our own GraphQL API. +## Sustainable web development -For the second delivery, the main focus has been establishing a working connection between the frontend, backend and database. The application currently retrieves artwork data from the database and presents the results in a responsive grid. Pagination is used to load a limited number of artworks at a time instead of loading the complete dataset into the client. +Sustainable web development has influenced several technical and design choices in Artex. -The application will be developed further with search, filtering, sorting, artwork details and persistent user-generated data in later deliveries. +Pagination ensures that only a limited number of artworks are retrieved at a time instead of transferring the complete database to the browser. Server-side filtering and sorting further reduce unnecessary client-side processing and data transfer. -## Get started +The main artwork search is triggered by form submission rather than every keyboard input, while artist search uses debouncing. This reduces unnecessary network requests. + +GraphQL allows each view to request only the fields it needs. The catalogue view therefore retrieves only the information required for artwork cards, while additional artwork information is fetched when the user opens an individual detail page. + +Artwork listings use smaller artwork image variants where available rather than unnecessarily requesting higher-resolution images. Missing images are handled using placeholders. + +Together, these choices reduce network traffic, browser memory usage and unnecessary client-side computation while also improving the scalability of the application. + +## Getting started Before running the project, make sure Node.js and npm are installed. -The project is divided into separate `frontend` and `backend` directories. +The repository contains separate `frontend` and `backend` directories. ### Frontend @@ -33,21 +132,25 @@ cd frontend npm install ``` -Start the development server with: +Start the development server: ```bash npm run dev ``` -The webpage will then be available at the local URL provided in the terminal, normally: +The application will normally be available at: -- http://localhost:5173/ +```text +http://localhost:5173/ +``` ### Database connection -The MongoDB database is hosted on the group’s virtual machine. When running the backend locally, an SSH tunnel is used to connect to the database. +The MongoDB database is hosted on the group's virtual machine. -Open a terminal and run: +When running the backend locally, an SSH tunnel can be used to connect to the database. + +Open a separate terminal and run: ```bash ssh -N -L 27018:127.0.0.1:27017 @it2810-12.idi.ntnu.no @@ -57,78 +160,86 @@ Replace `` with your NTNU username and keep the terminal open while ru ### Backend -Open a new terminal, navigate to the backend directory and install the dependencies: +Navigate to the backend directory and install the dependencies: ```bash cd backend npm install ``` -Start the backend with the MongoDB connection through the SSH tunnel: +The backend requires a `JWT_SECRET` for authentication. + +Create a `.env` file in the backend directory and add: + +```env +JWT_SECRET= +``` + +A random secret can for example be generated with: + +```bash +openssl rand -hex 32 +``` + +Start the backend while connected to the database through the SSH tunnel: ```bash MONGODB_URI=mongodb://127.0.0.1:27018 npm run dev ``` -When the connection is successful, the terminal should display: +The GraphQL backend is available locally at: ```text -Connected to MongoDB -Server running at http://127.0.0.1:3001/ +http://localhost:3001/ ``` -The GraphQL API will then be available at: +To run the complete application locally, the SSH tunnel, backend and frontend must run at the same time. -- http://localhost:3001/ +## Code quality and testing -To run the application locally, the SSH tunnel, backend and frontend must run at the same time. +The project uses ESLint and Prettier to maintain consistent and readable code. -## Developed by - -- Emma Fredriksen -- Mina Ellingsen -- Karen Skauge -- Gurveer Singh +Frontend linting can be checked with: -## Technologies +```bash +cd frontend +npm run lint +``` -The project is developed using the following technologies and tools: +Backend linting can be checked with: -- React -- Vite -- TypeScript -- Tailwind CSS -- React Router -- Lucide React -- Node.js -- GraphQL -- Apollo Server -- MongoDB -- ESLint -- Prettier +```bash +cd backend +npm run lint +``` -## Technical choices +Formatting can be checked with: -The application is divided into a frontend, backend and database. The frontend is built with React and TypeScript using Vite, while the backend is built with Node.js, TypeScript, GraphQL and Apollo Server. MongoDB is used to store the artwork data. +```bash +npx prettier . --check +``` -The frontend is divided into smaller React components to separate responsibilities and make the code easier to understand, maintain and test. Components such as the hero section, artwork cards, artwork grid and pagination can be developed and reused independently. +The application is structured into pages, reusable components, hooks, stores and types to separate responsibilities and make the code easier to maintain and test. -GraphQL is used for communication between the frontend and backend. This allows the client to request only the fields it needs and makes it possible to handle functionality such as pagination, search, filtering and sorting on the backend instead of loading the full dataset into the browser. +Testing will be expanded further towards the final delivery. The final project will include component testing using Vitest, API testing and automated end-to-end testing of important user flows. -Artwork results are loaded using pagination. The frontend sends a `limit` and `offset` to the GraphQL backend, and the backend retrieves only the corresponding artworks from the database. This approach was chosen with scalability in mind, since the application should be able to handle a much larger dataset without transferring all artwork data to the client at once. +For the third delivery, the primary focus has been completing and validating the functional prototype, including search, pagination, filtering, sorting, authentication, galleries, accessibility and sustainable development choices. -Artwork images use lazy loading so images are loaded when needed instead of all at once. Missing or unavailable images are handled by displaying a placeholder. These choices reduce unnecessary data transfer and are also part of our approach to sustainable web development. +## Use of AI -React Router is used for navigation between pages. Some navigation is temporary for the second delivery. For example, the profile icon currently leads to the login page and will be updated when the final profile and authentication flow is implemented. +AI has been used as a supporting tool during the development of Artex. -The design is based on our Figma prototype and is implemented responsively so that the layout adapts to different screen sizes. Accessibility is considered by using semantic HTML, appropriate alternative text and accessible labels for controls where needed. Accessibility and responsive behavior will be developed and tested further in later deliveries. +It has mainly been used for discussing implementation approaches, troubleshooting development and configuration issues, explaining unfamiliar technologies and concepts, reviewing code and suggesting improvements, discussing accessibility and sustainable web development, supporting documentation and wording, and identifying possible edge cases. -## Use of AI +AI-generated suggestions are reviewed and adapted before being included in the project. The group aims to understand and be able to explain all code that is committed. -During development, AI has mainly been used as a supporting tool for discussing implementation approaches, troubleshooting errors, reviewing code, explaining unfamiliar technologies and concepts, and improving formulations in the README. +Issues, branches, pull requests and code reviews are used to maintain control over the development process and ensure that changes are reviewed and understood by the group. -We use AI as a coach rather than relying on generated solutions without understanding them. Suggestions are reviewed and adjusted before being included in the project, and we aim to understand and be able to explain the code we commit. +AI is therefore used primarily as a development and learning aid rather than as a replacement for the group's own implementation and technical decisions. -AI has, among other things, been used to help troubleshoot the local development setup between the React frontend, GraphQL backend and MongoDB database, discuss responsive design and accessibility, review possible implementation choices, and help formulate parts of the project documentation. +## Developed by -We use issues, pull requests and code reviews to maintain control over the development process and to make sure changes are understood and reviewed by the group. Our use of AI will continue to be documented and updated as the project develops. \ No newline at end of file +- Emma Fredriksen +- Mina Ellingsen +- Karen Skauge +- Gurveer Singh \ No newline at end of file