Refactor: split the single-file codebase into focused modules

[JoywinNeilLasrado]

Overview

The entire application currently lives in one file: src/Qrip.py (~3,700 lines). There are no tests, no separate modules, and no separation of concerns. This makes the code hard to navigate, difficult to test, and intimidating for new contributors.

This is a gradual refactor — do not attempt to split everything at once. Each step below is a self-contained PR.

Suggested extraction order

Each step should be done as a separate PR. After each one, verify the app still runs correctly before moving on.

• Step 1 — Lyrics module: Extract all LRCLIB fetching and lyrics display logic into src/lyrics.py. This is the most self-contained piece and a good starting point.
• Step 2 — Credentials module: Extract _apply_stored_credentials() and all accounts.json read/write logic into src/credentials.py.
• Step 3 — Config module: Extract config file read/write logic (once Save app preferences to a config file (~/.config/qrip/config.json) #54 is done) into src/config.py.
• Step 4 — Downloader module: Extract the subprocess/PTY download logic and output parsing into src/downloader.py.
• Step 5 — Services module: Extract service URL detection, API calls, and metadata fetching into src/services.py (see also Extract service detection logic into a single reusable structure #62).

How to approach each step

1. Identify all related functions/methods in src/Qrip.py
2. Move them to the new module file
3. Update imports in Qrip.py
4. Run the app manually and verify the affected feature still works

Goal

src/Qrip.py becomes a thin UI layer that wires together focused, independently readable modules — each of which can eventually have its own tests.

Good starting point for new contributors: Step 1 (lyrics module) is the most isolated and well-defined piece. It's a great way to get familiar with the codebase.

[TheZupZup]

Hey! Thanks a lot for opening this 🙌
Really appreciate you taking the time to think about improving the project like this.

I totally agree that modularizing the codebase would be a great step forward 👍
To make it easier for everyone to contribute, I think it could be nice to split this into smaller issues (core, UI, config, etc.).

If you’re interested, I’d be more than happy to collaborate on this with you or let you take a part of it 🙂

Thanks again for your contribution

[JoywinNeilLasrado]

definitely i would love to work with you on this

[TheZupZup]

That was fast 😄 really appreciate the quick reply!

Yeah I think this could turn into something really nice for the project.
Would you like to start by taking one part of the modularization (for example core, UI or config)?

I can also help define the structure if you want so we stay consistent 👍

[TheZupZup]

Hey, I’m heading to sleep for now
I’ll take a closer look at this tomorrow and we can continue from there

Thanks again for the idea, really appreciate it ❤️

[TheZupZup]

@JoywinNeilLasrado Hey! I'm back 🙂

I took some time to think about the structure, and I’d really like to move forward with the modularization.

If you're still up for it, feel free to pick a part you'd enjoy working on (core, UI, config, etc.), and we can start organizing things from there.

Really happy to collaborate on this 👍

[TheZupZup]

Progress update — partial:

Some extraction has begun outside the listed steps:

• ✅ Error parsing extracted to src/core/errors.py (parse_streamrip_error)
• ✅ Status markup extracted to src/core/status.py (build_status_markup)

The originally proposed steps remain pending:

• ⏳ Step 1 — Lyrics module (src/lyrics.py)
• ⏳ Step 2 — Credentials module (src/credentials.py)
• ⏳ Step 3 — Config module (src/config.py)
• ⏳ Step 4 — Downloader module (src/downloader.py)
• ⏳ Step 5 — Services module (src/services.py — see also Extract service detection logic into a single reusable structure #62)

Keeping open.

---

Generated by Claude Code