GO — Healthy across the board

• Last commit 3d ago
• 16 active contributors
• Distributed ownership (top contributor 45% of recent commits)
• MPL-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Suwayomi-Server is a desktop rewrite of Tachiyomi (a manga reader app) that runs as a JVM-based backend server with web/client frontends. It provides manga browsing, reading, library management, and extension support across Windows, macOS, and Linux without Android dependencies, using Kotlin/Java with Gradle-based build infrastructure. Multi-module Gradle monorepo: AndroidCompat/ provides Android annotation shims and config management (ConfigManager.kt, ApplicationRootDir.kt) so desktop code reuses Tachiyomi logic; main server code elsewhere (inferred); separate client projects in other repos. Build uses Gradle Kotlin DSL (build.gradle.kts files), with CI publishing Docker images, Windows installers via winget, and platform-specific executables.

Manga enthusiasts and developers who want a cross-platform, self-hosted manga reader alternative to mobile-only Tachiyomi; contributors extend it via extensions (similar to Tachiyomi plugins) or improve the server/client core. Used by both end-users running desktop bundles and developers building alternative client UIs (web, native, etc.).

Production-ready with active CI/CD (GitHub Actions workflows for build, Docker, winget publishing), organized multi-module Gradle build (AndroidCompat, Server modules), and organized release channels (stable + preview). Project is actively maintained with multiple deployment targets (OS bundles, Docker, package managers) and integration tests in pipelines, indicating solid maturity.

Medium risk: depends on Kotlin ecosystem (requires JVM compatibility across platforms) and extension system (3rd-party extension quality not guaranteed). Architecture splits Android compatibility shim (AndroidCompat/) from core, which is good, but the large Java codebase (3.4MB) with Kotlin interop (1.8MB) increases cognitive overhead. Last observed activity is recent based on workflow configs, but watch for platform-specific issues (Windows, macOS, Linux differences).

Active CI/CD pipeline handling pull requests (build_pull_request.yml), pushes to main (build_push.yml), Docker stable releases (docker_build_stable.yml), winget updates (winget.yml), and wiki sync. Repository accepts issues (bug_report.yml, feature_request.yml templates exist) and PRs (pull_request_template.md exists), indicating ongoing community contributions.

git clone https://github.com/Suwayomi/Suwayomi-Server.git
cd Suwayomi-Server
./gradlew build
./gradlew run

(On Windows, use gradlew.bat instead of ./gradlew; Makefile suggests alternative build targets may exist.)

Daily commands:

./gradlew build
./gradlew run

Docker: docker pull suwayomi/server:latest && docker run suwayomi/server (workflows reference docker_build_stable.yml). For release JARs: java -jar suwayomi-server.jar. OS bundles (Windows .exe, macOS .dmg, Linux AppImage) are pre-built in GitHub Releases.

• AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManager.kt — Central configuration management system that loads and manages all application settings; understand this first to know how the app is configured.
• AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ApplicationRootDir.kt — Defines the root directory for all application data and configuration files; critical for understanding file system layout and data persistence.
• AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManagerModule.kt — Dependency injection module that wires the configuration system; necessary for understanding how configuration is injected throughout the application.
• AndroidCompat/src/main/java/android/content/Context.java — Android compatibility shim providing Context interface to a desktop application; foundational abstraction bridging Android and desktop paradigms.
• AndroidCompat/src/main/java/android/app/Application.java — Android Application lifecycle compatibility layer; essential for understanding how the desktop app mimics Android application startup and lifecycle.
• AndroidCompat/src/main/java/android/arch/persistence/db/SupportSQLiteDatabase.java — Database abstraction layer providing SQLite support; critical for all data access patterns used throughout the server.
• .github/workflows/build_push.yml — Primary CI/CD pipeline defining build, test, and deployment processes; understand this to know how code reaches production.

• Android Compatibility Layer (AndroidCompat) — Provides Android API stubs (Context, Application, Intent, SharedPreferences) and database abstractions (S

Add a new configuration setting

1. Define the config property in your feature's config class or create a new one in AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ (AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManager.kt)
2. Implement config loading logic in ConfigManager to read from properties file (AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManager.kt)
3. Wire the config object into the DI container in ConfigManagerModule (AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManagerModule.kt)
4. Inject the config object where needed using Dagger or manual injection (AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigModule.kt)

Add a new database table and access layer

1. Create a data entity class to represent your table rows (AndroidCompat/src/main/java/android/arch/persistence/db/SupportSQLiteDatabase.java)
2. Create a DAO (Data Access Object) interface with query methods (AndroidCompat/src/main/java/android/arch/persistence/db/SupportSQLiteDatabase.java)
3. Use SupportSQLiteDatabase to create table schema in migrations (AndroidCompat/src/main/java/android/arch/persistence/db/SupportSQLiteOpenHelper.java)
4. Implement the DAO using SimpleSQLiteQuery and SupportSQLiteStatement (AndroidCompat/src/main/java/android/arch/persistence/db/SimpleSQLiteQuery.java)

Add a new service or feature module

1. Create your service class in the appropriate package following existing structure (AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigModule.kt)
2. Add configuration requirements for your service in ConfigModule (AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigModule.kt)
3. Create a Dagger Module to provide your service as a dependency (AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManagerModule.kt)
4. Update build.gradle.kts to add new dependencies required by your service (AndroidCompat/build.gradle.kts)

• Kotlin + Java — Desktop JVM runtime provides cross-platform capability and leverages Tachiyomi's existing Android codebase through compatibility shims.
• SQLite with AndroidArch Persistence — Lightweight, embedded database suitable for desktop applications; Android compatibility layer allows direct reuse of Tachiyomi data layer.
• Gradle + Kotlin DSL — Build system familiar to Android developers; Kotlin DSL improves readability and enables type-safe dependency management.
• GitHub Actions CI/CD — Native GitHub integration for automated testing, building, and releasing across multiple platforms (Windows, Linux, macOS).
• Dagger-like DI — Dependency injection provides loose coupling, testability, and centralized configuration management through ConfigManagerModule.

• Android compatibility layer instead of native desktop APIs

  • Why: Allows maximum code reuse from original Tachiyomi; minimizes duplicate logic.
  • Consequence: Additional abstraction layer adds overhead; some Android-specific behaviors may not translate perfectly to desktop.

• Embedded SQLite instead of remote database

  • Why: Single-user desktop application doesn't need concurrent access; simplifies deployment and eliminates external dependencies.
  • Consequence: Cannot scale to multiple simultaneous users; limited analytics and monitoring capabilities.

• JVM desktop application instead of native compiled binary

  • Why: Enables rapid iteration and code sharing with Android version; cross-platform with single codebase.
  • Consequence: Requires JVM runtime on user machine; larger memory footprint; slower startup than native apps.

• Real-time synchronization across multiple devices
• Multi-user concurrent access
• Cloud backup or remote data storage
• Native platform integration (menu bars, system tray on all platforms)
• Support for Android as a runtime target

1. Platform-specific paths: ApplicationRootDir.kt likely handles Windows/Mac/Linux differences; config file locations vary by OS (watch for hardcoded separators). 2. Extension system security: AndroidCompat/ is a shim, so actual Tachiyomi extension loading happens elsewhere (not in this file list); malicious extensions are a risk. 3. JVM version constraints: Build likely requires Java 11+ (check build.gradle.kts for sourceCompatibility); mismatched JVM versions cause runtime errors. 4. Config file format: ConfigManager.kt deserializes settings; breaking the config format breaks existing user setups—migrations needed. 5. Gradle wrapper: Uses gradlew; offline builds may fail if dependencies aren't cached (check gradle/wrapper/gradle-wrapper.jar).

• Android Compatibility Shim — Suwayomi reuses Tachiyomi code designed for Android; AndroidCompat/ provides fake Android classes so JVM-only code compiles without the full Android SDK.
• Plugin/Extension System — Tachiyomi (and Suwayomi) dynamically load manga source extensions; understanding how ConfigManager.kt and the server discover/initialize extensions is key to extending functionality.
• Cross-Platform JVM Packaging — Project distributes as Windows .exe, macOS .dmg, Linux AppImage via CI; understanding GraalVM native images, jlink, and OS-specific bundlers (winget, Homebrew) is essential for release engineering.
• Configuration Management Patterns — ConfigManager.kt centralizes settings; learning how it serializes/deserializes (likely YAML, JSON, or HOCON) and handles versioning is critical for adding new features without breaking existing configs.
• GitHub Actions CI/CD Workflows — The .github/workflows/ directory orchestrates builds, Docker images, and multi-platform releases; understanding how workflows condition jobs by branch/tag is essential for testing and deploying changes.
• Gradle Multi-Module Builds — AndroidCompat and main server are separate modules with distinct dependencies; knowing how to declare inter-module dependencies and manage transitive deps prevents subtle classpath issues.
• Server-Client Architecture (REST/HTTP implied) — This repo is the backend; Suwayomi-WebUI and other clients communicate via API (likely REST); understanding request/response contracts and session management is needed to add server features.

• tachiyomiorg/tachiyomi — The original Android manga reader that Suwayomi-Server reimplements for desktop; shares extension API and manga source ecosystem.
• Suwayomi/Suwayomi-WebUI — Official web client frontend for Suwayomi-Server; runs in browser and communicates with this server via REST API.
• Suwayomi/Tachidesk-Sorayomi — Desktop client UI for Suwayomi-Server (alternative to WebUI); demonstrates how to build native clients against the server backend.
• Suwayomi/Suwayomi-Server-preview — Nightly/preview release channel; tracks bleeding-edge builds and tests new features before stable release.
• keiyoushi/manga-extensions — Community extension repository compatible with Suwayomi; extensions add manga sources (scrapers) dynamically.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for AndroidCompat annotation classes

The AndroidCompat module contains ~40 Android annotation stub classes (AnimRes.java, ColorInt.java, etc.) but there are no visible test files. These annotations are critical for compile-time type safety when porting Android-specific code. Adding tests would verify the annotations work correctly with Kotlin/Java tools and serve as documentation for how they're used in the codebase.

• [ ] Create AndroidCompat/src/test directory structure
• [ ] Add test class for annotation retention and target verification (e.g., AnnotationMetadataTest.kt)
• [ ] Test that annotations compile without runtime errors across key ones: @NonNull, @DrawableRes, @StringRes, @MainThread
• [ ] Verify annotation targets match expected usage in ConfigManager.kt and other core files
• [ ] Add tests to CI workflow (build_pull_request.yml) if not already running test tasks

Create ConfigManager integration tests in AndroidCompat/Config

ConfigManager.kt and ConfigModule.kt are critical initialization components for the server, but there are no visible test files in AndroidCompat/Config/src. These handle application root directory resolution, logging setup, and dependency injection—all prone to environment-specific failures. Integration tests would catch cross-platform issues (Windows vs Linux paths, permission issues).

• [ ] Create AndroidCompat/Config/src/test/java/xyz/nulldev/ts/config directory
• [ ] Add ConfigManagerTest.kt testing initialization with mock ApplicationRootDir
• [ ] Add test for ConfigExtensions.kt utility functions with various input scenarios
• [ ] Test ConfigModule dependency bindings are correctly wired
• [ ] Include tests for temporary/cache directory creation and permissions on different OS

Add workflow for code quality checks (linting/static analysis)

The repo has CI workflows for building and Docker deployment (build_pull_request.yml, docker_build_stable.yml) but appears to lack static analysis checks. For a Kotlin/Java desktop server project, Detekt (Kotlin linter) and SpotBugs or Sonarqube integration would catch common bugs in ConfigManager initialization, resource leaks, and threading issues before merge.

• [ ] Add Detekt dependency and configuration (detekt-gradle-plugin) in root build.gradle.kts
• [ ] Create .detekt/detekt.yml with rules appropriate for server code (disable UI-related rules)
• [ ] Add GitHub Actions workflow file: .github/workflows/code_quality.yml that runs on PRs
• [ ] Configure workflow to fail PR if critical issues found (e.g., potential null pointer exceptions)
• [ ] Add detekt task to existing build.gradle.kts and verify it runs in CI

• Add missing Android annotation stubs to AndroidCompat/src/main/java/android/annotation/: Tachiyomi may reference newer Android APIs (e.g., @RequiresApi, @UiThread) that don't exist yet in the shim—scan Tachiyomi source and add missing ones.
• Write Gradle integration tests in build.gradle.kts to verify cross-platform builds (Windows path handling, macOS code signing readiness, Linux binary stripping) since CI only shows basic build success—add test tasks that validate output artifacts.
• Document the extension loading flow: README mentions extensions but this file list doesn't show the loader—trace where AndroidCompat/Config hands off to extension discovery and write ADR (Architecture Decision Record) explaining how extensions are sandboxed/versioned, then add to docs/.

The Suwayomi-Server codebase shows a moderate security posture based on available information. Key concerns include: (1) incomplete dependency information preventing vulnerability assessment, (2) potential SQL injection risks in the database abstraction layer, (3) missing visibility into Docker/infrastructure security configurations, and (4) lack of comprehensive input validation framework in the visible file structure. The project appears to be a legitimate rewrite of Tachiyomi with Android compatibility layers, but critical security files and configurations were not fully available for analysis. Recommendations include conducting a full dependency audit, implementing parameterized database queries throughout, documenting and hardening Docker deployment configurations, and implementing centralized input validation. The low score reflects the analysis limitations rather than confirmed vulnerabilities in visible code.

• Medium · Incomplete Dependency Analysis Due to Missing Package Files — build.gradle.kts files, package.json, or equivalent dependency management files. The dependency/package file content was not provided for analysis. This prevents identification of vulnerable or outdated dependencies that could introduce security risks into the application. Fix: Provide complete dependency manifests (build.gradle.kts, settings.gradle.kts, package.json, etc.) for comprehensive vulnerability scanning. Use dependency checking tools like OWASP Dependency-Check, Snyk, or Gradle's built-in dependency vulnerability scanning.
• Medium · Potential SQL Injection Risk in AndroidCompat Database Layer — AndroidCompat/src/main/java/android/arch/persistence/db/SimpleSQLiteQuery.java. The codebase includes SimpleSQLiteQuery.java which may be used for raw SQL query construction. Without visibility into actual usage patterns, there is a risk of SQL injection if user input is concatenated directly into queries. Fix: Ensure all database queries use parameterized statements or prepared statements. Implement input validation and sanitization. Use ORM frameworks or query builders that automatically escape parameters. Conduct code review of all database access patterns.
• Medium · Missing Security Configuration Details — Docker configuration files, application configuration, and deployment setup. The security context regarding Docker/Config snippets and README sections was not fully provided, making it impossible to verify proper security configurations, exposed ports, security headers, and runtime security settings. Fix: Implement security best practices: (1) Use non-root user in Docker containers, (2) Implement security headers (CSP, X-Frame-Options, etc.), (3) Restrict exposed ports, (4) Enable HTTPS/TLS, (5) Implement authentication and authorization controls, (6) Use secrets management for sensitive data.
• Low · Android Annotation Imports Without Security Validation — AndroidCompat/src/main/java/android/annotation/ directory. The codebase includes numerous Android annotations for resource validation (AnimRes, DrawableRes, etc.) but these are primarily for compile-time checking and do not provide runtime security validation. Fix: While annotations are helpful for development, ensure runtime validation is also implemented for user inputs and external data sources. Use proper validation libraries and security frameworks for runtime protection.
• Low · Lack of Visible Input Validation Framework — Application codebase (not visible in provided file structure). No comprehensive input validation or sanitization framework is evident from the file structure provided. This could lead to various injection attacks if user inputs are not properly validated. Fix: Implement a centralized input validation framework. Use whitelist-based validation where possible. Validate all user inputs on both client and server sides. Consider using security libraries specific to your framework (e.g., OWASP ESAPI).

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Suwayomi/Suwayomi-Server shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Suwayomi/Suwayomi-Server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Suwayomi/Suwayomi-Server.

What it runs against: a local clone of Suwayomi/Suwayomi-Server — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Suwayomi/Suwayomi-Server | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Suwayomi/Suwayomi-Server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Suwayomi/Suwayomi-Server.git
#   cd Suwayomi-Server
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Suwayomi/Suwayomi-Server and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Suwayomi/Suwayomi-Server(\\.git)?\\b" \\
  && ok "origin remote is Suwayomi/Suwayomi-Server" \\
  || miss "origin remote is not Suwayomi/Suwayomi-Server (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManager.kt" \\
  && ok "AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManager.kt" \\
  || miss "missing critical file: AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManager.kt"
test -f "AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ApplicationRootDir.kt" \\
  && ok "AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ApplicationRootDir.kt" \\
  || miss "missing critical file: AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ApplicationRootDir.kt"
test -f "AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManagerModule.kt" \\
  && ok "AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManagerModule.kt" \\
  || miss "missing critical file: AndroidCompat/Config/src/main/java/xyz/nulldev/ts/config/ConfigManagerModule.kt"
test -f "AndroidCompat/src/main/java/android/content/Context.java" \\
  && ok "AndroidCompat/src/main/java/android/content/Context.java" \\
  || miss "missing critical file: AndroidCompat/src/main/java/android/content/Context.java"
test -f "AndroidCompat/src/main/java/android/app/Application.java" \\
  && ok "AndroidCompat/src/main/java/android/app/Application.java" \\
  || miss "missing critical file: AndroidCompat/src/main/java/android/app/Application.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Suwayomi/Suwayomi-Server"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.