This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Optimized tool selection

Updated todo list

What this project is

• AnimeTV is a TV-friendly anime streaming app for Android TV / Google TV, plus a desktop Electron version.
• It does not host anime itself; it pulls data and stream links from an external source site and related services.
• The app is built to work like a local client: it stores watch history, watchlists, and settings on the device instead of on a project server.
• The codebase is in a transition state: the newer TypeScript clean-architecture layer is done, but the older web UI code is still part of the live app.

How the whole app fits together

• There are two main host layers: Electron on desktop and Android WebView on Android devices.
• Both hosts load the same web-based app shell and then expose native capabilities into that page.
• The frontend is mostly a WebView app, not a traditional native Android UI.
• The page loads scripts that include both the newer typed bridge and older legacy UI code.
• User actions like remote control keys, search, navigation, and playback are handled by the page, but the host app supplies platform-specific support such as window control, storage, and media behavior.

Backend / host side in plain terms

• The “backend” here is not a remote server; it is mostly the Electron main process or the Android app process.
• On desktop, Electron launches a browser window, handles app lifecycle, and injects platform behavior into the page.
• On Android, the Java app creates the WebView, handles lifecycle, and translates Android key events into web app actions.
• A TypeScript container wires together the core logic, repositories, and use cases, so the app logic is separated from platform details.
• The app uses request interception, DNS controls, and specialized networking because the upstream source site is not a simple static HTML site.

Frontend side in plain terms

• The frontend is the in-app web page that users actually see and navigate.
• It contains the home screen, search, details pages, playback UI, watchlist, settings, and TV-style focus navigation.
• The older UI bundle still powers much of the interface, while the newer typed bridge exposes cleaner APIs for newer code.
• The frontend talks to the host through a bridge object, similar to how frontend JavaScript might call into native features in an embedded app.

What happens when the app starts

• The host app opens the main page inside a WebView or browser window.
• The page loads the bridge code and the legacy UI scripts.
• The bridge decides whether it is running on Android or desktop and loads the right platform adapter.
• Once loaded, the page can request anime lists, search results, episode data, and stream sources through the bridge.
• When playback starts, the app fetches stream links from the external source and passes them to the player UI.

How data flows

• User opens the app.
• The page asks the bridge for home data, search results, episode lists, or stream sources.
• The bridge calls into TypeScript domain logic and data sources.
• The data layer talks to the upstream source site or supporting APIs.
• Results come back to the page, which renders them in the TV UI.
• Watch history and watchlist changes are saved locally.

Why this architecture matters

• The new TypeScript layer makes the core logic easier to test and reason about.
• The old UI still exists because it already works and replacing it all at once would be risky.
• The clean separation helps contributors change one part without rewriting everything.
• For someone coming from Python or web development, the closest mental model is:
• host app = runtime wrapper
• bridge = API boundary
• domain layer = business logic
• data layer = adapters for external sources
• frontend page = UI and interaction layer

Current project status

• The clean-architecture migration is marked complete.
• The main unfinished work is stability and modernization, not core feature delivery.
• Biggest open items are E2E testing, migration of old UI modules to TypeScript, better error handling, and documentation.
• The SPA rewrite is currently parked, so it is not the active path for the main app.

Main risks

• The app depends on an external site that can change without warning.
• Many features rely on JavaScript injection and browser-like behavior, so upstream changes can break playback or scraping.
• Some of the UI still uses legacy code, so changes can accidentally affect both the old and new layers.
• Full end-to-end testing is not in place yet, which means regressions are easier to miss.

If you want to contribute

• Start by understanding whether the change belongs in the host app, the bridge, the TypeScript core, or the web UI.
• Prefer small, focused changes with tests.
• If you touch anything related to data fetching or playback, verify both Electron and Android paths.
• If you touch the UI, check whether the change affects the old m.js runtime, the clean-arch bridge, or both.
• The safest first contributions are usually documentation fixes, test additions, bug fixes in the bridge, or small legacy-module refactors.

Best mental model

• Think of this as a web app running inside a native shell.
• The native shell provides device features and starts the app.
• The web layer handles the actual screens and interaction.
• The TypeScript layer is becoming the stable “engine” under the UI.
• The external anime source is effectively the app’s data provider, even though it is not owned by the project.

If you want, I can turn this into a “new contributor cheat sheet” with:

1. where to look for UI bugs,
2. where to look for playback bugs,
3. where to look for data-fetching bugs.