How suwayomi/suwayomi-webui works
Project Type and Purpose
• The Suwayomi-WebUI is a full-featured client application for manga management, reading, and library control. It is bundled with the Suwayomi-Server and communicates (largely via GraphQL) to provide a rich user interface for browsing manga, reading chapters, handling downloads, and more.
Analyzing the File Structure
• The top-level directories and files indicate standard configurations (.eslint, .prettierrc, tsconfig, vite.config.ts) along with a “public” folder (for static assets) and a very modular “src” directory.
• Within “src” you see many subdirectories such as:
– “modules” (which contain domain-specific functionality e.g., reader, manga, chapter, category, settings, etc.),
– “lib” (utility libraries for GraphQL, mui styles, requests, storage, and more),
– “i18n” (for internationalization),
– Supporting directories for assets, utilities, and tooling.
• This structure suggests a component-driven, possibly MVC-inspired or modular layered architecture where views, services, and data handling are clearly separated.
Main Components
a. User Interface (UI) Layer:
– Present modules (Library, Reader, Category, Chapter, Downloads, Settings, Sources, Tracker, Themes, etc.). Each module folder (e.g., “modules/reader”, “modules/manga”, “modules/chapter”) can be represented as separate “feature blocks” within the UI.
b. Data Access and API Integration:
– GraphQL integration is central. There’s a dedicated “src/lib/graphql” directory which handles queries, mutations, subscriptions, and generated code. Represent this as an API integration layer.
– Also note the “src/lib/requests/client” which includes REST and GraphQL clients.
c. Utility and Supporting Libraries:
– There are various “lib” and “util” directories that provide supporting functionalities like promise control, dayjs configuration for date handling, queue management, and storage.
– Context providers (inside modules like “core”, “device”, “theme”, “reader”, etc.) are used to maintain state across the application. Include an “Application State & Context” component.
d. External Services & Build/Dev Tools:
– The project uses external tools and workflows (GitHub workflows under “.github“) and build scripts for deployment.
– Also include external integrations like translations (with Weblate) and dependency on the Suwayomi-Server.
Relationships and Data Flow
• That context providers and state management layers (e.g., from “modules/core/contexts”, “modules/reader/contexts”, “modules/theme/contexts”, etc.) interconnect with UI modules, providing global state.
• Interactions between utility libraries (e.g., functions in “src/lib”, “src/util”) that serve both the UI and the data modules.
• That build scripts and configuration files are responsible for bundling the app, while GitHub workflows manage CI/CD for updates and releases.
Architectural Patterns & Design Principles
• Modularity: Separate features into distinct modules (library, reader, settings, etc.), each with its own components, hooks, and services.
• Clear separation of concerns between UI rendering, business logic (services and hooks), state management (contexts), and data fetching (GraphQL/REST clients).
• Utilize dependency injection via context providers/higher-order components ("hoc" in “modules/core/hoc/withPropsFrom.tsx”) to share functionality.
• That the system follows best practices in internationalization (numerous locales in “public/locales” and “src/i18n”) and robust error handling (ErrorBoundary components).