docs: update documentation for current architecture

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
 

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.

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)

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            |

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: