An open-source search engine that aggregates content across categories — JAV, anime, movies, comics, and novels, all in one place.
This repository contains both English and Chinese documentation.
English — this file is the English README. 中文(简体) — 查看中文 README
- Quick Access
- v1.8.0 Highlights
- Project Documentation
- Project Features
- Technology Stack Overview
- Quick Start
- Performance Optimization
- Security Features
- License
- Acknowledgments
- Contact and Support
| Resource Type | Link | Remarks |
|---|---|---|
| Online Experience | https://atlas.wort.uk/ | Try out all features |
- Multilingual query resolution: Chinese, Japanese, English and romanized titles resolve to the same work through a shared alias table; each source is queried in its own indexing language, and the admin console gains alias ingestion and review.
- Follow any entity: Directors, studios, publishers, series and tags can be followed alongside actresses; the follow feed filters by target and searches across everything you follow by keyword.
- Entity browsing from JAV details: Click a director, studio, publisher, series or tag on a detail card to browse their works, and the returned list is written back to the local library.
- Local library detail cards: Any history or favorite entry opens its local detail card, and every cover across the site zooms on click or keyboard.
- Admin data operations: The data storage console filters transient failures, retries or completes single records, resets source-missing counters, and caps the 30-day retry queue per day.
- Faster, steadier data: Cached panel polling, single-pass statistics, snapshot caches and new indexes cut D1 reads sharply; rankings import, magnet detection and the four media search paths were reworked.
The project uses a modular documentation system, where each specialized documentation is maintained independently.
| Document | Description | Link |
|---|---|---|
| Configuration Documentation | Frontend configuration, backend configuration, environment variables, proxy services, database configuration, role permission configuration | docs/config.md |
| Deployment Guide | Environment requirements, local development, backend deployment, frontend deployment, database configuration, FAQ | docs/deploy.md |
| Version Changelog | Complete version change records: v1.0.0 (first public release), v1.1.0 (anime & movie search + architecture upgrade), v1.2.0 (comic search + architecture optimization), v1.3.0 (novel search + aggregation view + observability), v1.4.0 (JAV actress search + data storage management + community improvements), v1.5.0 (unified workbench + trilingual i18n + rankings & recommendations), v1.6.0 (help center + unified notification inbox + email delivery), v1.7.0 (library-first JAV search + tag recommendations + PWA/mobile + single-Worker deployment), v1.8.0 (multilingual query aliases + entity follows + local library detail cards + D1 read reduction) | docs/CHANGELOG.md |
| GitHub Push Guide | Git operation process, submission specifications, branch management, GitHub Actions automatic deployment configuration | docs/github_push.md |
| Client Packaging & Signing | Windows/Android client shells, version numbering rules, Android/Windows signing keys, release flow | docs/app-packaging.md |
| Document | Description | Link |
|---|---|---|
| Notification Component Documentation | Toast notification component usage, API documentation, configuration options, and best practices | frontend/docs/notification.md |
- JAV Search: Aggregates metadata from DMM/FANZA and searches magnets from JavBus/JavDB, with a new actress search submode (v1.4.0 new, data source JavBus). Code searches hit the local collection first when magnets exist, and the detail card offers a one-click JavBus refresh that writes back to the local collection. Directors, studios, publishers, series and tags open browsable work lists that are written back to the local library (v1.8.0).
- Anime Search: Aggregates data from Bangumi, Mikan, and DMHY, including subtitles (nyaa source disabled due to deployment environment restrictions, v1.4.0 adjusted)
- Movie Search: Aggregates metadata from TMDB, YTS, EZTV, and TPB, including seeds and magnets
- Comic Search: Aggregates metadata from MangaDex and MangaUpdates plus 13 search sources
- Novel Search: Aggregates book metadata from Anna's Archive and TXT direct links from Qishu (v1.3.0 new; Qishu now served from qishuxia.com)
- Unified Experience: All five categories are accessible from a single entry, with search results aggregated from multiple sources
- React 19 + TypeScript: Utilizes the latest React features with complete type safety provided by TypeScript
- Vite Ultra-fast Build: Millisecond-level hot updates and a silky smooth development experience
- Tailwind CSS: An atomic CSS solution that supports seamless switching between light and dark themes
- Zustand State Management: A lightweight state management solution with automatic persistent storage
- Cloudflare Full-Stack Deployment: A single Cloudflare Worker serves both the static frontend (Workers Static Assets) and the API, with D1 for the database — fully serverless and deployed from one pipeline
- Global CDN Acceleration: Leverages Cloudflare's 300+ global edge nodes for user-proximity access
- Zero Operational Costs: No need to purchase servers; the free tier can support small to medium-sized applications
- Automatic Elastic Scaling: Automatically scales during peak traffic, eliminating concerns about server crashes
- JWT Stateless Authentication: Token-based authentication implemented with the jose library, supporting automatic refresh
- Comprehensive Email Verification: Includes registration verification, password reset, email change, and account deletion, all with email confirmation
- Multi-Layer Security Mechanisms: Features login failure lock, verification code frequency limits, temporary email blacklists, and security event logs
- RBAC Permission System: Implements a four-level role permission system (Super Admin, Administrator, User, Guest) with fine-grained permission control
- Unified Notification Center: Community interactions, actress follow updates, and site announcements share one inbox, one unread badge, and one set of in-app / email preferences
- Built-in Help Center:
/helpdocuments every user-facing module, with feature overviews, step-by-step guides, and per-category caveats
React 19 → Concurrent rendering, Suspense, automatic batching
TypeScript → Complete type inference, generic constraints, type guards
Vite → Native ESM support, on-demand compilation, ultra-fast HMR
Tailwind CSS → JIT compilation, dark mode, responsive design
Zustand → Ultra-simple API, middleware support, persistent storage
@codeseek/shared → Monorepo shared package (types, utilities, validation rules)
React Router → Data routing, lazy loading, nested layout
Lucide React → 1000+ beautiful icons, Tree-shaking optimization
date-fns → Lightweight date handling, internationalization support
Hono 4.x → Ultra-lightweight web framework with multi-runtime support
TypeScript → Type safety, interface definition, generic constraints
Cloudflare Workers → Edge computing, V8 isolation environment, zero cold start
Cloudflare D1 → SQLite-compatible, globally distributed, with automatic backup
JWT (jose) → Standardized authentication, support for multiple algorithms
Cloudflare Email Sending / Mailtrap / Resend / Brevo → Transactional email with provider priority and daily quotas
- Mobile-First: Perfectly adapts to all device sizes, from 320px to 4K monitors
- Touch Optimization: Supports gesture operations, sliding menus, and long-press interactions, providing a mobile experience comparable to native apps
- Performance Priority: First-screen load time under 1 second, interaction response time under 100ms, with a Lighthouse score of 90+
- Toast Notification System: Unified message prompts with four types: success, error, warning, and information
- Automatic Data Synchronization: Cross-device synchronization of search history, favorites, and personal settings
- Theme Customization: Supports light, dark, and system-following themes, with one-click switching and state persistence
- Shortcut Key Support: Common operations support keyboard shortcuts, improving operational efficiency
| Category | Data Source | Description |
|---|---|---|
| JAV | DMM/FANZA / JavBus / JavDB / JavBus (actress profiles, v1.4.0 new) | Adult film metadata + magnet aggregation + actress profile search (JAV search, not code-only search) |
| Anime | Bangumi / Mikan / ShowRSS | Anime metadata + subtitle groups (nyaa source disabled due to deployment environment restrictions, v1.4.0 adjusted) |
| Movie | TMDB / YTS / EZTV / TPB | Movie/TV series metadata and seed resources |
| Comic | MangaDex / 13 search sources | Comic metadata and resource aggregation |
| Novel | Anna's Archive / Qishu | Book metadata and TXT direct link resources (v1.3.0 new) |
JAV search is refined into three submodes, with URL sub parameter persistence — refresh / forward-back / share links all restore correctly:
| Submode | Description |
|---|---|
| code (code search) | Default mode, precise metadata + magnet matching by code |
| actress (actress search) | Data source JavBus actress search (/searchstar → /star; the former minnano-av source is now behind anti-bot protection), parses actress profiles (name / birthday / age / measurements / birthplace / hobbies / avatar), and auto-supplements JavBus works list. Click a work card to jump to code search |
| title (title search) | Fuzzy match by title keyword |
Actress search keywords auto-convert to Japanese (mapping table + opencc simplified-to-Japanese conversion fallback), supporting direct search with Chinese nicknames; actress cards support favorites and sharing to community.
Category (large category) Classification (subcategory) Source (source instance)
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
│ jav │ ────> │ metadata │ ────> │ DMM/FANZA │
│ │ │ magnet │ │ JavBus │
│ │ │ │ │ JavDB │
├─────────────┤ ├──────────────────┤ ├──────────────┤
│ anime │ ────> │ bangumi │ ────> │ Bangumi API │
│ │ │ mikan │ │ Mikan Project│
│ │ │ nyaa │ │ Nyaa.si │
│ │ │ showrss │ │ ShowRSS │
├─────────────┤ ├──────────────────┐ ├──────────────┤
│ movie │ ────> │ tmdb │ ────> │ TMDB API │
│ │ │ yts │ │ YTS │
│ │ │ eztv │ │ EZTV │
│ │ │ tpb │ │ TPB │
├─────────────┤ ├──────────────────┐ ├──────────────┤
│ manga │ ────> │ mangadex │ ────> │ MangaDex API │
│ │ │ sources │ │ 13 search sources │
├─────────────┤ ├──────────────────┐ ├──────────────┤
│ novel │ ────> │ anna-archive │ ────> │ Anna's Archive│
│ │ │ qishu │ │ Qishu │
└─────────────┘ └──────────────────┘ └──────────────┘
Core Design:
- Provider Registration Mode: Adding a new search category only requires creating a Provider class and registering one line in
backend/src/index.ts - Classification Independent Routing: Each classification has independent search logic and result panels
- Database-Driven Source Management: Enable/disable/weight of search sources managed through backend administration
- One-Click Aggregation: Select category and classification, input keyword, and display results from all sources
- Intelligent Sorting: Sort results based on search source priority, usage frequency, and availability status
- Classification Filtering: Support filtering by large category (JAV/Anime/Movie/Comic/Novel) and sub-classification
- Fixed Source Management: One-click fix common search sources for personalized customization (v1.2.0 new feature)
- Aggregation View: Work-level resource grouping, multi-source resources merged per work (v1.3.0 new)
- Asynchronous Data Collection: Search results asynchronously persisted to DB with deduplication and multi-source merging, anonymous design storing no user info (v1.4.0 new)
- History Record: Automatically save search history (with cover image), support quick re-search and history statistics
- Smart Prompt: Automatically prompt related search suggestions when typing a keyword
- Hot Search: Real-time display of hot search keywords, helping discover popular resources
- Search Statistics: Personal search statistics to understand search habits
- Enable/Disable: Free control which search sources participate in search
- Priority Adjustment: Customize search source display order
- Status Monitoring: Real-time view of search source availability
- Custom Addition: Support adding custom search sources (URL template)
- GitHub OAuth Login: One-click login with GitHub account, automatically creating/associating an account
- Google OAuth Login: One-click login with Google account (v1.3.0 new)
- JWT Token Authentication: Stateless authentication with automatic token refresh support
- Login Protection: Automatically lock after 5 consecutive failed attempts for 15 minutes
- Session Management: View active sessions and support forced logout
- Favorites: Favorite commonly used search results (support all categories: JAV/Anime/Movie/Comic/Novel), with classification management
- Search History: Automatically record search history (with cover thumbnail), support clear and delete
- Data Sync: Cross-device synchronization of favorites, history, and settings
- Data Export: Support export personal data (JSON format)
- Favorites & History Pagination: Server-side pagination with totals; console statistics are aggregated server-side (v1.6.0)
- One Inbox: Follow updates for any followed entity — actress, director, studio, publisher, series or tag (
follow.new_work/follow.release_soon) — plus community likes / comments / favorites / report results, and site announcements, merged into/dashboard/notifications - Read-Time Announcement Merge: Announcements stay in
site_announcements; the inbox merges them on read and only stores each user's read/dismissed state inuser_announcement_reads - Per-Type Preferences: Independent in-app and email switches for every notification type; email cannot be enabled before the address is verified
- Email Verification Entry: The notification preferences page can send and verify an email code without leaving the page
- Inbox Actions: All / unread views, mark as read, delete one, clear all read, and an unread badge in the navigation bar
- Test Email: Send a test message from the preferences page (rate limited to once per minute per user)
- Share Search Sources: Share discovered useful search sources with the community
- 6 Share Categories Expanded: Supports full-category content sharing across JAV / Anime / Movie / Comic / Novel / Actress (v1.4.0 improved — original manga / actress / novel links were broken, now fixed)
- Tag Management: Add tags to search sources for easy classification search
- Review Mechanism: Admin review required before listing to ensure quality
- Comment Rating: Publish reviews on search sources to help others choose
- Like/Favorite: Like quality search sources and collect them in personal list
- Report Mechanism: Report inappropriate content, with admin processing
- View De-duplication (v1.6.0): The same user viewing the same post only increments
view_countonce per 24 hours (author self-views never count); requiresdatabase/04_community.sql - Unified Notifications (v1.6.0): Likes, comments, favorites, and report results are delivered to the unified notification inbox; the separate community notification tab and its legacy endpoints were removed
- Personal Contribution: View number of shared search sources, download count, and rating
- Community Rankings: Hot shares and active contributor rankings
- Multiple Feedback Types: Problem feedback, optimization suggestions, others
- Anonymous Support: Unregistered users can also submit feedback
- Automatic Collection: Automatically record page URL and browser information
- Status Tracking: View feedback processing status (pending/waiting/solved/closed)
- Email Notification: Automatic email notification after feedback processing completed
- History Record: View own feedback history
- User List: Paginated query, search filtering, status view
- Role Permissions: Four-level roles (Super Admin, Administrator, User, Guest)
- Status Control: Enable/disable user accounts
- Login Logs: View user login records and IP information
- Search Source Management: CRUD system for search sources and classifications (support five major categories)
- Data Storage Management: Search results asynchronously persisted to DB with deduplication, multi-source merging; browse / hide / cleanup stale data by type, with statistics overview (v1.4.0 new)
- Community Review: Review user-shared search sources
- Report Processing: Process user-reported content
- Announcement Management: Publish, edit, and delete announcements; publishing enqueues announcement emails, and deleting removes pending queue entries (v1.6.0)
- Email Send Logs: Admin page lists every message with type, status, user, IP, and error details (
GET /api/config/email/logs) - Email Queue: Inspect pending / sent / skipped / failed digest tasks, including the last failure reason (
GET /api/config/email/queue) - Unified Sender: All transactional and notification mail goes through one sender with Cloudflare Email Sending, Mailtrap, Resend, or Brevo; provider priority, per-provider daily quotas, logging, and rate-limit metadata are configurable from the admin console
- Dashboard: One-view system operation status and user activity
- Trend Analysis: User growth, search trends, activity changes
- Behavior Logs: User operation behavior record and analysis
- Configuration Management: Dynamic modification of system configuration without redeployment
- JavDB Weekly / Monthly: censored and uncensored rankings, 20 entries per tab
- Daily Import: GitHub Actions imports weekly and monthly snapshots every day
- History Retained: ranked works are never deleted; current tabs only show the latest snapshot
- Trending Actresses: 30-day favorites/search heat plus ranked works, no random sampling
- Number Suggestion: Input keyword to automatically match numbers
- Multi-Source Data: Support multi-source data aggregation display
- Login Required: Need user login authentication to access
- Route:
/help, linked from the main navigation - Categories: Getting started, discovery (for-you / Recently Hot / TOP250 / trending actresses), search basics & tab differences, category guides, detail page, community, actress follows, notifications & email, account security, general notices, FAQ
- Structure: Every section follows “feature overview + step-by-step guide + caveats”, plus a standalone general notices chapter
- Consistency: Content is kept in sync with shipped behavior; JAV search is named “JAV search” everywhere instead of “JAV code search”
Frontend Layer (v1.6.0)
- React 19 + TypeScript
- Vite / Tailwind CSS / Zustand / React Router
- AnimeSearchResultPanel / MovieSearchResultPanel
- MangaSearchResultPanel (v1.2.0)
- NovelSearchResultPanel (v1.3.0)
- JavActressResultsPanel + ActressesPanel (v1.4.0)
- DataStorageTab (v1.4.0)
- Workbench components + trilingual i18n (v1.5.0)
- HelpCenterPage + help content definitions (v1.6.0)
- Notification bell / inbox / preferences pages (v1.6.0)
- Deployment: Cloudflare Workers (Workers Builds, Git-connected)
Provider Layer (v1.6.0)
- SearchProvider interface + ProviderRegistry
- anime-provider (Bangumi / Mikan / ShowRSS)
- movie-provider (TMDB / YTS / EZTV / TPB)
- manga-provider (MangaDex / 13 search sources)
- novel-provider (Anna's Archive / Qishu / zxcs)
- jav-provider (Metadata / Magnet + Actress submode)
- recommendation / ranking services (v1.5.0)
Backend Service Layer (v1.6.0)
- Hono Framework / TypeScript
- Cloudflare Workers / D1
- JWT authentication (jose) / Cloudflare Email Sending / Mailtrap / Resend / Brevo
- D1 persisted rate limiting (v1.3.0)
- Google OAuth (v1.3.0)
- Data storage management (v1.4.0)
- opencc Simplified-to-Japanese conversion (v1.4.0)
- Search tier quotas + JavDB rankings (v1.5.0)
- Unified notification service + follow feed + email sender/queue/log (v1.6.0)
- Monorepo shared package: TypeScript
paths+ Vite alias point directly atpackages/shared/src(v1.6.0)
- Node.js: >= 18.0.0
- npm: >= 9 (the repository uses npm workspaces;
package-lock.jsonis committed at the root) - Cloudflare Account: For deploying Workers and D1 database
- Wrangler CLI: Cloudflare development tool (>= 3.x)
# Clone project
git clone https://github.com/Zoroaaa/Atlas.git
cd Atlas
# Install dependencies (npm workspaces)
npm install
# Create the D1 database and keep the returned database_id for backend/wrangler.toml
npx wrangler d1 create codeseek
# Initialize a fresh database by running every script in database/ in filename order.
# All scripts are idempotent, so partial reruns are safe.
for f in database/[0-9]*.sql; do
npx wrangler d1 execute codeseek --remote --file="$f"
done
# Local development (two terminals; frontend runs on :3000 and proxies /api to :8787)
npm run dev --workspace=backend
npm run dev --workspace=frontend
# Production deployment
npm run build --workspace=frontend
npm run deploy --workspace=backendSee Detailed Deployment Guide See Configuration Instructions See v1.8.0 Changelog
- React 19 concurrency features + Vite fast build
- Code splitting, route-level lazy loading, tree-shaking
- Zustand persistent state + API response cache
- React.memo and useMemo optimization to reduce re-rendering
- Search cache layer to reduce repeated requests (v1.3.0 new)
- Cloudflare global edge nodes for near-source processing
- Database index optimization + parameterized queries
- Response compression (gzip/brotli) + batch operation support
- Request throttling + concurrency control + degradation strategies
- D1 persisted multi-level rate limiting (v1.3.0 new)
- XSS protection + CSRF protection
- Content Security Policy (CSP) + Subresource Integrity (SRI)
- JWT Token authentication + request signature verification
- Self-built frontend error monitoring observability system (v1.3.0 new)
- JWT Token authentication (jose library) + RBAC permission control
- SQL injection protection + password encryption storage (bcrypt)
- Login failure locking mechanism + security event logs
- CORS configuration + rate limiting + IP recording
- Email registration whitelist validation (v1.3.0 new)
This project is licensed under the MIT License.
You are free to:
- Use - for any purpose, including commercial use
- Modify - modify the source code to suit your needs
- Distribute - share the project or its modifications
- Private Use - use in private projects
But you must:
- Retain Copyright Notices - keep original copyright notices and license text
- State Modifications - indicate changes made to the source code
-
Cloudflare - providing an excellent edge computing platform
-
GitHub - code hosting and collaboration platform
-
Cloudflare Email Service - email sending
-
Mailtrap - email sending service
-
Brevo - email sending service
-
Resend - email sending service
Thanks to all developers who contribute to the open source community!
- Project Homepage: GitHub - Atlas
- Issue Reporting: GitHub Issues
- Feature Suggestions: GitHub Discussions
We welcome all forms of contributions:
- Report Bugs
- Propose New Features
- Improve Documentation
- Submit Code
- Translate Documentation
- Fork this repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit changes (
git commit -m 'Add some AmazingFeature') - Push to branch (
git push origin feature/AmazingFeature) - Open a Pull Request
JAV / Anime / Movies / Comics / Novels, one-stop search
Made with ❤️ by Zoro