Skip to content

Improve project documentation #57

Merged
merged 2 commits into from
Oct 18, 2026
+212 −234
Merged

Improve project documentation #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e309a9d
docs: improve project documentation
agnesas Oct 18, 2026
511c52e
add project link to root readme
agnesas Oct 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 43 additions & 154 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<img src="docs/images/phone_view.png" width="250">

# 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:
<img src="docs/images/phone_view.png" width="250" alt="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 <username>@it2810-24.idi.ntnu.no
```
MariaDB is used instead of the originally planned MySQL database.

Replace `<username>` 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 <username>@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.
117 changes: 117 additions & 0 deletions backend/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```
Loading