diff --git a/README.md b/README.md index b0a0045..365bea0 100644 --- a/README.md +++ b/README.md @@ -1,188 +1,77 @@ -# T24-Project-2 +# Pokémon Draft Planner -Repository for team IT2810-H26-T24 in IT2810-H26. +Repository for team IT2810-H26-T24 in IT2810 – Web Development at NTNU. -## Working in this repository +**Web application:** [Open Pokémon Draft Planner](http://it2810-24.idi.ntnu.no/project2) -`main` is protected — you cannot push to it directly. Work on a branch and -open a pull request: +Pokémon Draft Planner is a web application for exploring Pokémon data and planning draft teams. The goal is to let users search for Pokémon, create teams, and explore relevant information such as moves, stats, and type weaknesses across different Pokémon formats and generations. -```bash -git checkout -b my-feature -git push -u origin my-feature -``` +## Project Status -Before a pull request can be merged: +The current implementation includes: -1. **A member of IT2810-H26-T24 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. +- A MariaDB database containing Pokémon data. +- A GraphQL API built with Node.js, TypeScript, and Apollo Server. +- GraphQL queries for retrieving lists of Pokémon and individual Pokémon by ID. +- A React frontend using Apollo Client to retrieve and display Pokémon. ---- +The frontend currently displays a list of Pokémon. Search, team building, and other planned features are not yet fully implemented. -# Plan +## Dataset -The project plan is to build an application that displays information about a Pokèmon draft. This will involve being able to search through Pokèmon to set up teams, save than, and display information on them. This information will include move access, common vulnerabilities and stats. Adding to this, one should be able to select format, meaning that if you select RBY (Generation 1), only Pokèmon from gen 1 with the moves and stats they had back then should apper. While one would think just 1000+ Pokèmon is not a particularly large dataset, with the relations between moves, formats and Pokèmon, needing to relate them in an orderly manner, and having to conjoin data for the Natdex-formats who keeps cut content, the need for scalable solution are certainly present. +The project uses data from [Pokémon Showdown by Smogon](https://github.com/smogon/pokemon-showdown/tree/master). -## ![Example from prep spreadsheet]() +This dataset was chosen because its structure and coverage of competitive Pokémon data better suit the project's requirements than alternatives such as PokéAPI. It also helps account for differences between generations and historical game mechanics, such as changes to the type chart. -# Dataset +## Design and Prototype -The following dataset will be used: -https://github.com/smogon/pokemon-showdown/tree/master +The initial user interface was designed and prototyped in Figma. These images show the planned interface and do not necessarily reflect all currently implemented functionality. -This choice has been made because the dataset in question is made in a format which is a lot more appropriate for our needs, compared to the alternative PokeAPI. It also helps keeping mechanic-changes like the type chart in consideration. - -# Figma prototype - -The initial user interface was designed and prototyped in Figma. - -## Desktop - -### Search +**Desktop — Search** ![Desktop search](docs/images/desktop_search.png) -### Ability +**Desktop — Ability** ![Desktop ability](docs/images/desktop_ability.png) -## Mobile - - - -# Architecture - -The overall system architecture is shown below. - -![System architecture](docs/images/architecture.svg) - -For a more detailed explanation of the architecture, see -[Architecture documentation](docs/architecture.md). - -# Backend Setup - -The backend uses Node.js, TypeScript, Apollo Server, GraphQL, and MariaDB. It exposes a GraphQL API that the React frontend uses to retrieve Pokémon data. - -## Requirements - -- Node.js and npm (Node.js 24 or newer) -- Access to the environment where the backend and database will run -- MariaDB with the Pokémon dataset imported - -## Installation - -From the repository root, run: - -```bash -cd backend -npm install -``` - -## Database Configuration - -Create a `.env` file in the `backend` directory with the following variables: - -```dotenv -DB_HOST=127.0.0.1 -DB_PORT=3306 -DB_USER=your_database_username -DB_PASSWORD=your_database_password -DB_NAME=pokemon -``` - -Replace the username and password placeholders with valid database credentials. Set the host and port to match your database configuration. - -When running the backend locally on your Mac and connecting to MariaDB on the NTNU VM through an SSH tunnel, use the local tunnel endpoint instead: - -```dotenv -DB_HOST=127.0.0.1 -DB_PORT=3307 -``` - -Keep your actual database credentials in `.env`. Do not commit `.env` files or database credentials to the repository. - -## Build and Start the Backend - -From the `backend` directory, compile the TypeScript code: - -```bash -npm run build -``` - -Start the compiled server: - -```bash -npm start -``` - -For development with automatic restarts, use: - -```bash -npm run dev -``` - -The GraphQL API listens on port `3001` and is available at [http://localhost:3001/](http://localhost:3001/) from the machine running the backend. - -## Example GraphQL Queries - -Retrieve Pokémon: - -```graphql -query { - pokemons { - id - name - type - } -} -``` +**Mobile** -Retrieve one Pokémon by ID: +Mobile interface prototype -```graphql -query { - pokemon(id: "pikachu") { - id - name - type - } -} -``` +## Architecture -The `type` field contains the Pokémon's type or types as a string. The `pokemon` query returns `null` when no Pokémon matches the supplied ID. +The application follows a client-server architecture consisting of a React frontend, a GraphQL backend, and a MariaDB database. -## Frontend Integration +The backend and database run directly on the group's virtual machine without Docker. Apache HTTP Server is used to serve the frontend. -The React frontend uses Apollo Client to communicate with the GraphQL API. Configure the frontend's GraphQL endpoint to match the backend's accessible URL. +### Technology Stack -When the backend runs locally on your Mac and the database is on the NTNU VM, keep the database SSH tunnel open while using the application: +| Component | Technology | +| ---------- | ----------------------- | +| Frontend | React, TypeScript, Vite | +| API client | Apollo Client | +| Backend | Node.js, TypeScript | +| API | GraphQL, Apollo Server | +| Database | MariaDB | +| Web server | Apache HTTP Server | -```bash -ssh -N -L 3307:127.0.0.1:3306 @it2810-24.idi.ntnu.no -``` +MariaDB is used instead of the originally planned MySQL database. -Replace `` with your VM username. This tunnel forwards local port `3307` to MariaDB on the VM's port `3306`. +See [Architecture](docs/architecture.md) for the architecture diagram and further details. -If the backend itself runs on the VM and you want to access the GraphQL API locally, use a separate tunnel: +## Getting Started -```bash -ssh -N -L 3001:127.0.0.1:3001 @it2810-24.idi.ntnu.no -``` +See the relevant documentation for setup and development instructions: -Keep the relevant SSH session open while using the tunnel. +- [Frontend](frontend/README.md) +- [Backend and GraphQL API](backend/README.md) +- [Database setup](docs/database-setup.md) -## Importing the Dataset +## Testing and Development -The backend includes an import script for importing the Pokémon Showdown dataset. To run it, configure the database connection in `.env`, then execute: +Testing has so far been performed manually, including checking GraphQL queries and verifying data retrieval through the frontend. Automated testing is planned as development progresses. -```bash -npm run import -``` +The project is developed collaboratively using issues, branches, pull requests, and code reviews. The `main` branch is protected. -Run the import when needed; it may modify the database contents. +See [Git workflow](docs/git-workflow.md) for branch naming, review requirements, and merge conventions. diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..c56838c --- /dev/null +++ b/backend/README.md @@ -0,0 +1,117 @@ +# Backend + +The backend provides a GraphQL API for Pokémon Draft Planner. It is built with Node.js, TypeScript, Apollo Server and MariaDB. + +## Requirements + +- Node.js 24 or later +- npm +- A running MariaDB instance with the Pokémon dataset imported + +See [Database Setup](../docs/database-setup.md) for instructions on setting up the database. + +## Getting Started + +### 1. Install dependencies + +From the project root, navigate to the backend directory and install the dependencies: + +```bash +cd backend +npm install +``` + +### 2. Configure environment variables + +Create a `.env` file in the `backend` directory with the database connection settings: + +```env +DB_HOST=127.0.0.1 +DB_PORT=3306 +DB_USER=your_database_username +DB_PASSWORD=your_database_password +DB_NAME=pokemon +``` + +Replace the example username and password with your database credentials. Adjust the host, port and database name if necessary. + +**Do not commit the `.env` file** to version control. + +### 3. Import the Pokémon dataset + +With the database available and the environment variables configured, run the import script from the backend directory: + +```bash +npm run import +``` + +The script imports Pokémon data from Pokémon Showdown into MariaDB. The database must be accessible before running the import. + +### 4. Start the GraphQL server + +To start the server in development mode: + +```bash +npm run dev +``` + +To build and start the server in production mode: + +```bash +npm run build +npm start +``` + +The GraphQL server listens on port `3001`. When running locally, the endpoint is available at `http://localhost:3001/`. + +## GraphQL API + +The API currently supports retrieving lists of Pokémon and individual Pokémon by ID. + +### Retrieve Pokémon + +```graphql +query { + pokemons { + id + name + type + } +} +``` + +This query returns Pokémon records with their IDs, names and types. + +### Retrieve a Pokémon by ID + +```graphql +query { + pokemon(id: "pikachu") { + id + name + type + } +} +``` + +This query retrieves a single Pokémon. If no Pokémon matches the supplied ID, the resolver returns `null`. + +## Frontend Integration + +The React frontend uses Apollo Client to communicate with the GraphQL API. The frontend must be configured to use an endpoint that is reachable from the browser, and the backend must be running for API requests to succeed. + +When running the application on a remote server, ensure that the required database and API connections are available from the relevant environment. + +## Development Checks + +Run TypeScript type checking with: + +```bash +npm run typecheck +``` + +Build the backend to check that it compiles successfully: + +```bash +npm run build +``` diff --git a/docs/architecture.md b/docs/architecture.md index 755958f..e4bde67 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,28 +2,34 @@ ## Overview -In contrast to `IT2810-H26/T24-Project-1`, `IT2810-H26/T24-Project-2` has a -distinct frontend and backend. The backend is hosted on the group's virutal -machine, and will be responsible for the custom `GraphQL` backend, and we will use -`MySQL` as our database solution. `Apache2` will be used as the web server. +Pokémon Draft Planner is built using a client-server architecture with a separate frontend and backend. The frontend is built with React and TypeScript, while the backend provides a custom GraphQL API implemented with Node.js and TypeScript. The application is hosted on the group's virtual machine, where the backend and database run directly, without Docker. Apache HTTP Server is used to serve the frontend. -Refer to this diagram for an overview of the basic system architecture. -Deviations from this plan may occur depending on the direction of the project. +The project originally planned to use MySQL as its database solution. The implementation now uses MariaDB instead. + +Refer to the diagram below for an overview of the system architecture. It illustrates the intended architecture and may not reflect every implementation detail or planned feature. ![System Architecture](images/architecture.svg) ## Client -The client is responsible for the rendering of the UI Components. We will use -`React` to create reusable components for the frontend. Data will be stored on -the browser and is managed by `Apollo Client`. The user will be able to create -Pokemon Teams, which will be saved to their local browser storage so they are -persistent between sessions. These can later be published for other users to see -on the website by utilizing `GraphQL` to make a new database row. These other -teams can be liked to mutate the database row. +The client is responsible for rendering the user interface. React and TypeScript are used to build reusable UI components. + +Apollo Client handles communication with the GraphQL API and manages GraphQL operations and server data on the client. + +The application is intended to support searching and exploring Pokémon data, viewing details, and interacting with search results. + +The architecture also allows for user-created Pokémon teams to be stored in the browser and potentially published for other users to view and like. Features that require shared, persistent data must be supported by the backend and database. ## Backend -The backend hosts the `GraphQL API endpoint`. Queries made towards it will be -resolved and it will query the `MySQL` database, which holds the Pokemon data -imported from Smogon. +The backend exposes a GraphQL API implemented with Node.js, TypeScript, and Apollo Server. + +GraphQL resolvers handle incoming queries and retrieve Pokémon data from MariaDB. The database connection is managed by the backend. + +The API currently supports retrieving Pokémon data, including lists of Pokémon and individual Pokémon by ID. + +## Database + +MariaDB stores the Pokémon dataset imported from Smogon. A backend import script loads the dataset into the database. + +The database is accessed through the backend rather than directly from the frontend. Database connection settings are configured through environment variables. diff --git a/frontend/README.md b/frontend/README.md index 653fa86..c4f7998 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,78 +1,44 @@ -# React + TypeScript + Vite +# Frontend -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +The frontend of Pokémon Draft Planner is built with React, TypeScript and Vite. It uses Apollo Client to communicate with the backend's GraphQL API. -Currently, two official plugins are available: +## Requirements -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +- Node.js 24 or later +- npm +- A running backend with the GraphQL API accessible from the browser -## React Compiler +## Getting Started -The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information. +### 1. Install dependencies -Note: This will impact Vite dev & build performances. -You can also try [the experimental native React Compiler support in plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md#rust-react-compiler) by using `compiler: true` in the plugin options instead of using the Babel plugin. +From the project root, run: -## Expanding the ESLint configuration +```bash +cd frontend +npm install +``` -If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: +### 2. Start the development server -```js -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... +```bash +npm run dev +``` - // Remove tseslint.configs.recommended and replace with this - tseslint.configs.recommendedTypeChecked, - // Alternatively, use this for stricter rules - tseslint.configs.strictTypeChecked, - // Optionally, add this for stylistic rules - tseslint.configs.stylisticTypeChecked, +Vite starts the frontend development server. Follow the URL printed in the terminal to open the application in your browser. - // Other configs... - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +## GraphQL Integration -``` +The frontend uses Apollo Client to retrieve Pokémon data from the backend. The GraphQL endpoint must be configured to point to an address accessible from the browser. -You can also install [eslint-plugin-react-x](https://npmx.dev/package/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://npmx.dev/package/eslint-plugin-react-dom) for React-specific lint rules: - -```js -// eslint.config.js -import reactX from 'eslint-plugin-react-x' -import reactDom from 'eslint-plugin-react-dom' - -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... - // Enable lint rules for React - reactX.configs['recommended-typescript'], - // Enable lint rules for React DOM - reactDom.configs.recommended, - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +The backend currently provides queries for retrieving a list of Pokémon and an individual Pokémon by ID. See the [backend README](../backend/README.md) for setup instructions and example queries. -``` +## Current Functionality + +The frontend currently displays a list of Pokémon retrieved from the GraphQL API. Interactive functionality and additional features are still under development. + +## Related Documentation + +- [Project overview and setup](../README.md) +- [Backend setup and GraphQL API](../backend/README.md) +- [System architecture](../docs/architecture.md)