From bc43d326cbbc66e706bfb6662f03536659916dea Mon Sep 17 00:00:00 2001 From: siversm Date: Thu, 12 Nov 2026 09:40:59 +0100 Subject: [PATCH] docs: update documentation for current architecture - Correct schema and resolver documentation - Document rating mutations, sorting, and API test coverage - Clarify database testing limitations - Fix AI declaration wording and README link - Improve setup documentation wording Co authored: pederoha --- README.md | 2 +- docs/AI declaration.md | 18 ++++++++++-------- docs/Architecture.md | 26 +++++++++++--------------- docs/Setup.md | 2 +- docs/Testing.md | 21 +++++++++++---------- 5 files changed, 34 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 6eec027..1ebfb9a 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ For more information, see: - [Testing](docs/Testing.md) - [Performance testing](docs/Performance.md) - [Sustainability choices](docs/Sustainability.md) -- [AI declaration](docs/AI%20decleration.md) +- [AI declaration](docs/AI%20declaration.md) ## Working in this repository diff --git a/docs/AI declaration.md b/docs/AI declaration.md index 0191137..5051667 100644 --- a/docs/AI declaration.md +++ b/docs/AI declaration.md @@ -40,13 +40,15 @@ final implementation and documentation. the sustainability documentation. The content and final wording were reviewed by the team. - **`#57` - Rating system changes (10 November 2026):** - `Claude Opus 5.5` was consulted for rating system changes in order for logic to have fewer flaws, work with the current frontend implementations and generate tests for the new aggregate system. + `Claude Opus 5.5` was consulted about the rating system to reduce logic + errors, align it with the frontend, and generate tests for rating + aggregates. - **`#58` - Display average rating and vote count (10 November 2026):** - We consulted `Claude Opus 5.5` on how to show the rating aggregate in the + We consulted `Claude Opus 5.5` about displaying rating aggregates in the frontend. It helped me understand how ratings stored in their own table are - combined with the Pokémon data by the GraphQL server, and i used this to - decide on a separate `RatedPokemon` type and on letting `ratePokemon` return - the updated Pokémon so the Apollo cache updates without a refetch. It also - helped write parts of the display component and related tests. I - chose how the rating should look on the cards, tested the changes in the - browser, and reviewed the code and documentation before committing. + combined with Pokémon data by the GraphQL server, and I used this to decide + on a separate `RatedPokemon` type and have `ratePokemon` return the updated + Pokémon so Apollo Client can update its cache without a refetch. It also + helped write parts of the display component and related tests. I chose how + the rating should look on the cards, tested it in the browser, and reviewed + the code and documentation before committing. diff --git a/docs/Architecture.md b/docs/Architecture.md index 9f1e885..3e6e9a0 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -71,10 +71,17 @@ The server limits a request to a maximum of 100 Pokémon. It returns an `endCursor`, `hasNextPage`, and `hasPreviousPage` so the frontend can keep track of the current result window without loading the complete dataset. -The production GraphQL schema and resolver logic are defined in -`server/index.ts`. The server startup and seeding flow are handled there as -well. `server/schema.ts` contains the schema and resolver implementation used -by the API tests. +The GraphQL schema and resolver logic are defined in `server/schema.ts`, which +is used by both the running server and the API tests. `server/index.ts` is +responsible for checking whether the database needs seeding, fetching data +from PokeAPI with a local JSON fallback, and starting Apollo Server. + +The schema exposes the `pokemons` and `pokemon` queries and the `ratePokemon` +mutation. The `pokemons` resolver builds one parameterized SQL query from the +active search, type filter, cursor, and sorting options. Sort columns are +restricted to a whitelist because SQL identifiers cannot be supplied as +parameters. Sorting by `rating` uses the requesting voter's ID to order +Pokémon by that voter's own rating. ### Average rating and vote count @@ -128,12 +135,6 @@ server checks whether Pokémon already exist. If the database is empty, it fetches data from PokeAPI and falls back to the local JSON data if the external request fails. -> **Suggested diagram:** A database diagram would be useful here. It should -> show `pokemons` at the center, with one-to-many relationships to `abilities` -> and `types`, and the `ratings` table connected through `pokemon_id`. It would -> make the foreign keys and the composite rating key easier to understand than -> a text description alone. - ## Frontend-backend communication The frontend sends GraphQL requests over HTTP. A typical list request follows @@ -191,11 +192,6 @@ The external PokeAPI is used during initial database seeding rather than for every user search. Once the data is stored locally, normal application queries use SQLite. -> **Suggested architecture diagram:** If the project needs a broader system -> overview, create a diagram showing the browser, React/Apollo Client, -> Apollo GraphQL server, SQLite database, and PokeAPI. This would complement -> the database diagram rather than replace it. - ## Related documentation - [Setup](Setup.md) diff --git a/docs/Setup.md b/docs/Setup.md index 42c3d75..c28cc35 100644 --- a/docs/Setup.md +++ b/docs/Setup.md @@ -22,7 +22,7 @@ and to run the project use these commands (must also be ran from the project2 fo | `npm run dev` | Run the project (Frontend) | | `npm run dev:server` | Run the project (Server) | | `npm run dev:all` | Run the project (Everything) | -| `npm run build` | Build reactcode into html/js (For VM) | +| `npm run build` | Build the React application for the VM | | `npm run preview` | Preview the built project from `build` | | `npm run lint` | Run Eslint on the project | | `npm run format` | Run Prettier on the project | diff --git a/docs/Testing.md b/docs/Testing.md index 03c0720..bd57d6f 100644 --- a/docs/Testing.md +++ b/docs/Testing.md @@ -6,8 +6,9 @@ understand: - **Component tests** verify one React component at a time. They check the component's rendered output and user interactions without requiring the GraphQL server or database to run. -- **API tests** verify GraphQL requests against the server and its pagination, - search, filtering, and sorting behavior. These tests are implemented in +- **API tests** verify GraphQL requests against the schema and resolver layer, + including pagination, search, filtering, sorting, rating mutations, and + rating aggregates. These tests are implemented in `project2/server/test/api.test.ts`. > **Not yet implemented:** End-to-end tests for longer browser interactions @@ -52,14 +53,14 @@ Pokémon with no ratings returns `averageRating: null` and `ratingCount: 0`, that one and several votes give the right values, that the query is run for the correct Pokémon ID, and that every Pokémon on a page gets its own values. -The API tests use a mocked database, so they test that the resolvers pass the -values through correctly, but not that the SQL itself calculates the right -average. To check the SQL, we ran the real server against an empty test -database and sent ratings to it. The results matched what we expected: one -vote of 4 gave an average of 4, a second vote of 3 gave 3.5 with 2 votes, and -when the first voter changed their rating to 1 the average became 2 while the -count stayed at 2. An invalid rating of 9 was rejected. Turning this into an -automatic test against a real in-memory database would be a good next step. +The API tests use a mocked database. This verifies resolver behavior and SQL +parameter routing, but does not execute the queries against SQLite. Manual +testing against a real database confirmed that ratings are inserted and +updated correctly: one vote of 4 gives an average of 4, a second vote of 3 +gives 3.5 with 2 votes, and changing the first voter's rating to 1 changes +the average to 2 while the count stays at 2. Invalid ratings are rejected. +Automated integration tests against a temporary SQLite database would be a +useful future improvement. Run the component tests from the repository root: