Walkthrough support #2892

SaraVieira · 2026-01-11T12:55:50Z

Description
This PR adds a new tab in each rom for walkthroughs.

You can add walkthroughs:
- Uploads of PDF's, TXT and HTML
- Gamefaqs links
TRacks how much you read of the walkthrough

Missing

Clean up UI to add a walkthrough
Add LINK type of walkthrough
Move single walkthrough to a modal for more space

Checklist
^{Please check all that apply.}

I've tested the changes locally
I've updated relevant comments
I've assigned reviewers for this PR
I've added unit tests that cover the changes

Screenshots (if applicable)

gemini-code-assist · 2026-01-11T12:56:20Z

Summary of Changes

Hello @SaraVieira, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a significant new feature by integrating comprehensive walkthrough management directly into the application. It enables users to enrich their game library with guides from various sources, enhancing the overall user experience by centralizing game-related information and tracking their engagement with these guides.

Highlights

New Feature: Walkthrough Support: Introduced a new feature allowing users to add and manage walkthroughs for their ROMs. This includes a dedicated tab in each ROM's detail view.
Walkthrough Sources: Users can add walkthroughs by uploading PDF, TXT, or HTML files, or by providing links to GameFAQs guides. The system automatically fetches and processes content from GameFAQs.
Reading Progress Tracking: The system now tracks how much of a walkthrough a user has read, providing a progress indicator.
Backend API and Database Changes: A new walkthroughs table has been added to the database, along with new API endpoints for fetching, creating, uploading, listing, and deleting walkthroughs. The RomSchema has been updated to include associated walkthroughs.
Frontend Components: New Vue components (Walkthroughs.vue, WalkthroughPanel.vue) have been developed to display walkthroughs within the game details and manage them in the ROM editing dialog. A useWalkthrough composable handles display logic and reading progress.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a significant new feature for managing walkthroughs for ROMs, including fetching from GameFAQs and uploading local files (PDF, HTML, TXT). The backend implementation is comprehensive, with new API endpoints, database models, and handlers. The frontend is also updated with new components to display and manage these walkthroughs. The code is generally well-structured, but I've identified a few areas for improvement regarding code duplication, database efficiency, and type safety in the frontend. I've also found a potential bug related to a missing enum value in the auto-generated frontend types.

frontend/src/__generated__/models/WalkthroughFormat.ts

backend/endpoints/walkthrough.py

backend/handler/walkthrough_handler.py

frontend/src/services/api/rom.ts

SaraVieira · 2026-01-11T13:22:09Z

I'm on all of these reviews

SaraVieira · 2026-01-11T13:40:26Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a comprehensive feature for managing walkthroughs for ROMs. The changes span across the backend and frontend, including new database tables, API endpoints, file handling, and UI components.

The backend implementation is solid, with good error handling and security considerations like HTML sanitization. The frontend work is also well-structured, with a dedicated composable for the walkthrough viewer logic, which includes nice features like progress tracking and virtual scrolling.

I've identified a few areas for improvement:

A potential data inconsistency issue in the PDF upload logic due to multiple database transactions.
Some minor code cleanup opportunities, such as removing an unused function parameter and an unused import.
A suggestion to improve method naming for better clarity.

Overall, this is a great addition to the application. Please see my detailed comments for specific suggestions.

backend/endpoints/walkthrough.py

backend/handler/database/walkthroughs_handler.py

backend/handler/walkthrough_handler.py

frontend/src/components/common/Game/Dialog/EditRom/WalkthroughPanel.vue

SaraVieira · 2026-01-11T13:49:38Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a comprehensive walkthrough feature, including backend support for fetching from GameFAQs, file uploads (PDF, HTML, TXT), and database storage, along with a well-designed frontend interface for managing and viewing walkthroughs. The implementation is solid, with good error handling and security considerations like HTML sanitization. I've identified a few areas for improvement, including a data handling bug in the frontend, a minor inconsistency in a database migration file, and an opportunity to make exception handling more specific in one of the endpoints. Overall, this is a great addition to the application.

frontend/src/components/common/Game/Dialog/EditRom/WalkthroughPanel.vue

backend/alembic/versions/0064_walkthroughs.py

backend/endpoints/walkthrough.py

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

SaraVieira · 2026-01-11T14:11:53Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a comprehensive feature for managing and viewing walkthroughs for ROMs. The changes are well-structured, spanning the database schema, backend APIs for fetching and managing walkthroughs from GameFAQs and file uploads, and a polished frontend interface for display. The implementation is robust, featuring solid error handling, security measures like HTML sanitization, and a thoughtful user experience for reading long guides. I have one minor suggestion to enhance MIME type handling for Markdown file uploads.

backend/handler/walkthrough_handler.py

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

gantoine

first review coming your way (sorry for the wait), still need to look at walkthrough_handler but i'll do that in my editor another

gantoine · 2026-01-15T00:18:43Z

backend/alembic/versions/0064_walkthroughs.py

+        sa.Column("author", sa.String(length=250), nullable=True),
+        sa.Column(
+            "source",
+            sa.Enum("GAMEFAQS", "UPLOAD", name="walkthroughsource"),


would copying the contents as text be labeled as "UPLOAD", or do we need a "MANUAL" for it (like writing a note)?

gantoine · 2026-01-15T00:19:16Z

backend/alembic/versions/0064_walkthroughs.py

+            nullable=False,
+        ),
+        sa.Column(
+            "format",


i don't think we should save this since we can use the filename to get the format, and that offers us more flexibility in displaying content

gantoine · 2026-01-15T00:19:46Z

backend/alembic/versions/0064_walkthroughs.py

+            sa.Enum("html", "text", "pdf", name="walkthroughformat"),
+            nullable=False,
+        ),
+        sa.Column("file_path", sa.String(length=1000), nullable=True),


would like to see file_name and file_path stored separately like we do for roms

gantoine · 2026-01-15T00:20:34Z

backend/endpoints/walkthrough.py

+        log.error("Walkthrough fetch failed", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY, detail=str(exc)
+        ) from exc


gantoine · 2026-01-15T00:21:17Z

backend/endpoints/walkthrough.py

+async def get_walkthrough(
+    request: Request,  # noqa: ARG001 - required for authentication decorator
+    payload: WalkthroughRequest,
+) -> WalkthroughResponse:


why not use WalkthroughSchema here?

gantoine · 2026-01-15T00:21:55Z

backend/endpoints/walkthrough.py

+    if ext in {".html", ".htm"}:
+        return WalkthroughFormat.HTML
+    if ext in {".txt", ".text", ".md"}:
+        return WalkthroughFormat.TEXT


re my comment earlier, this can be a computed @Property on the model or in pydantic

gantoine · 2026-01-15T00:24:31Z

backend/models/rom.py

        lazy="raise", back_populates="rom"
    )
    rom_users: Mapped[list[RomUser]] = relationship(lazy="raise", back_populates="rom")
+    walkthroughs: Mapped[list["Walkthrough"]] = relationship(


strings not necessary if its only imported when type checking

Suggested change

walkthroughs: Mapped[list["Walkthrough"]] = relationship(

walkthroughs: Mapped[list[Walkthrough]] = relationship(

gantoine · 2026-01-15T00:25:10Z

backend/pytest.ini

+   D:DB_HOST=127.0.0.1
+   D:DB_NAME=romm_test
+   D:DB_USER=romm_test
+   D:DB_PASSWD=passwd


what does D: do?

SaraVieira added 4 commits January 11, 2026 12:39

feat/walkthroughs

8239cab

remove extra migration; clean more steam stuff

3e59bea

clear up design

043d55e

fix ts

91039be

gemini-code-assist bot reviewed Jan 11, 2026

View reviewed changes

SaraVieira added 2 commits January 11, 2026 13:30

fix types

35bf03a

remove dead code

2854752

gemini-code-assist bot reviewed Jan 11, 2026

View reviewed changes

SaraVieira added 2 commits January 11, 2026 13:44

fix migartion conflict

e17345b

better naming and error handling

511ed84

gemini-code-assist bot reviewed Jan 11, 2026

View reviewed changes

frontend/src/components/common/Game/Dialog/EditRom/WalkthroughPanel.vue Outdated Show resolved Hide resolved

backend/alembic/versions/0064_walkthroughs.py Outdated Show resolved Hide resolved

backend/endpoints/walkthrough.py Show resolved Hide resolved

SaraVieira and others added 2 commits January 11, 2026 13:53

Update backend/alembic/versions/0064_walkthroughs.py

ec4232b

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

clean up frontend and make adding a rom one step

6dd9d6a

gemini-code-assist bot reviewed Jan 11, 2026

View reviewed changes

backend/handler/walkthrough_handler.py Show resolved Hide resolved

Update backend/handler/walkthrough_handler.py

506d75d

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

gantoine self-requested a review January 11, 2026 14:46

SaraVieira added 2 commits January 11, 2026 15:10

divide panel in several files

8e81117

flex mahgic

100aca8

gantoine changed the title ~~Feature - Add walkthrough support~~ Walkthrough support Jan 14, 2026

gantoine requested changes Jan 15, 2026

View reviewed changes

	walkthroughs: Mapped[list["Walkthrough"]] = relationship(
	walkthroughs: Mapped[list[Walkthrough]] = relationship(

Uh oh!

Walkthrough support #2892

Are you sure you want to change the base?

Walkthrough support #2892

Uh oh!

Conversation

SaraVieira commented Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Screenshots (if applicable)

Uh oh!

gemini-code-assist bot commented Jan 11, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SaraVieira commented Jan 11, 2026

Uh oh!

SaraVieira commented Jan 11, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SaraVieira commented Jan 11, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SaraVieira commented Jan 11, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gantoine left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SaraVieira commented Jan 11, 2026 •

edited

Loading