Manga / Anime Explorer

Project Team Info

Our team has three members, and each person worked on different parts of the project:

• Zihan Gao
  Built login, registration, item saving to the library, and search functionalities.
  Created frontend pages including the home page, search page, details page, library page, and login page.

• Danyang Yan
  Added sorting and filtering features to the library page, enabling users to sort saved items in various ways.
  Refactored the backend by splitting the large run.py file into smaller modules, improving project maintainability and readability.
  Implemented the character card feature. UML Diagram Creation

• Boyi Zhao
  Worked on the recommendation system by analyzing the user's saved items, calculating preferences, and retrieving suitable anime/manga from the API based on these patterns.
  Designed the layout for the main home page.

Description

This project is a web application that allows users to browse, search, and save information about anime and manga. The frontend is built with React to create the user interface, and the backend uses Flask to provide API services and SQLite to store user accounts and Library records. All data comes from the Jikan API, and the backend keeps a local cache of external API responses to reduce repeated requests and improve loading speed.

When visiting the website, users can register an account and log in. Their login information is stored in the database. After logging in, their Library data is synchronized with the backend. As a result, when using the same account on different devices within the same local network, users will see the same personal Library.

When logged in, users can do several things:

1. Browse a list of popular anime and manga recommended by the system on the Home page.
2. Search for anime or manga based on keywords and filter conditions on the Search page.
3. Add favorite titles to their personal Library and write notes for each item.
4. View automatic recommendations generated by the system on the Recommendation page based on the items already saved in the Library.

All Library information (such as which titles were saved, whether the title is anime or manga, the cover image URL, personal notes, etc.) is stored in the LibraryItem table in the backend database. Therefore, as long as the backend service is accessible on the same network (for example, through the server’s IP address on the same WiFi), logging in with the same account on another device will display the same Library data instead of creating separate copies.

This project also implements two important features:

First, the backend performs local caching when accessing the external Jikan API. It checks the ApiCache table, and if the requested data has been fetched within the last 6 hours, the backend returns the cached version instead of making a new external API call. This reduces the number of requests sent to Jikan and avoids issues related to API rate limits.

Second, the recommendation system is based on the user's Library. The backend retrieves all titles saved by the user, determines whether the user prefers anime or manga, and then calls Jikan’s Top API for that category. It selects high-rated titles of the corresponding type, formats them, and returns them to the frontend as recommendations.

The Details page also includes a Character list. When the user opens the Details page, the frontend sends three requests to Jikan simultaneously: one for the title details, one for the character list, and one for similar recommendations. These parallel requests allow the page to load more quickly.

When clicking a character in the list, the frontend calls the backend’s character details endpoint. The backend fetches complete character information from Jikan’s character/full endpoint and caches it. The frontend then displays the character's image, name, Japanese voice actor, favorites count, and detailed description in a modal window.

In simple terms, the goal of this project is to:

• Use an external anime/manga API as the data source,
• Use a local database to store user accounts and personal Library items,
• Add caching and recommendation mechanisms,
• Build an application that supports login, cross-device access, searching, saving favorites, and viewing character information for anime and manga.

Features

1) User Registration and Login

• Users can create a new account on the website by entering a username and password.
• The backend checks whether the username already exists. If not, it saves the username and the hashed password into the User table.
• After registration, users can log in with their account. Once logged in, the backend generates a JWT token and returns it to the frontend. The frontend stores the token and username in the browser. When accessing “My Library” or “Recommendations,” the token must be included.

2) Home Page (Home / Discover)

• The Home page displays a selection of “Top Anime” and “Top Manga.”
• This data is not fetched directly from Jikan on the frontend. Instead, it is obtained through the backend’s /api/top/anime and /api/top/manga endpoints. The backend calls Jikan’s Top API, caches the result in the local database, and returns a processed list to the frontend.
• Users can click any item on the Home page to open its Details page.

3) Search

• Users can enter keywords on the Search page (for example, part of a title such as “Naruto”) to search for anime or manga.
• Search type can be selected: Anime or Manga.
• Sorting options include: by score, popularity, year, or alphabetical order.
• Users can apply.filters:
  • By genre (e.g., Action, Comedy, Romance, etc.)
  • By rating (G, PG, PG-13, R, etc.)
  • By year (e.g., 2020, 2021)
• Search requests are sent to the backend’s /api/search endpoint. The backend constructs the Jikan query URL and uses the local caching system to reduce repeated calls. The results are returned with pagination, and the frontend provides a full pagination bar for navigation.

4) Details Page

When users click an item from the Home page or Search results, they enter the item’s Details page:

• The top section displays the poster, title, score, number of ratings, year, status (airing/completed), and other basic information.
• An “Add to Library” button allows users to save the title to their Library. If already saved, it will show “Already in Library.”
• The middle section contains three tabs:
  • Overview: displays the synopsis and genre tags.
  • Characters: lists the characters, each with an image, name, role (main/supporting), and favorites count.
  • Similar: displays similar titles provided by Jikan, shown as small cards linking to MyAnimeList.

On this page, the frontend sends three requests to Jikan simultaneously: one for details, one for characters, and one for similar titles. This parallel loading makes the page faster.

5) Character Card / Character Modal

• In the Details page’s Characters tab, each character is clickable.
• When the user clicks a character, the frontend calls the backend endpoint /api/character/<character_id>. The backend checks whether complete character data exists in the cache. If it is missing or expired, the backend requests full character data from Jikan’s characters/{id}/full endpoint and stores it in ApiCache.
• The frontend opens a modal window showing the character’s large image, English and Japanese names, favorites count, nicknames, detailed description, and one Japanese voice actor (with image + name). If some information is missing, a friendly placeholder message is shown.

6) My Library

• When logged in, users can open the Library page to see all titles they have saved.
• Each entry displays the cover image, title, type (Anime / Manga), and a Personal Notes section.
• Users can delete any saved item. The frontend updates the list immediately and attempts to call the backend /api/library/<mal_id> DELETE endpoint. If the backend is unreachable, the list is backed up to the browser’s local storage.
• Users can also click Edit to modify the personal notes for a title. Saving the changes sends a PUT request to the backend; if the backend is unavailable, the changes are saved locally.
• When the backend is connected, the bottom of the Sidebar shows “Database Connected.” If disconnected or errors occur, it shows “Local Mode,” and the Library page indicates that local storage is being used.

7) Recommendation

• The Recommendation page provides suggestions based on the titles saved by the logged-in user.
• The backend reads all LibraryItem entries for the user and determines which type appears more often (e.g., anime appears more than manga). That type is treated as the user’s preference.
• The backend then calls Jikan’s top/{preferred_type} API to retrieve high-rated titles of that type and returns a formatted recommendation list.
• The frontend displays the recommendations in rows of cards, and shows a heading like “Recommended for You (anime)” or “Recommended for You (manga)”. If the user has not saved any items, a message appears instructing them to add titles to the Library first.

SetUp

I. Preparing the Backend Environment (Flask + SQLite)

1) Install Python
A Python 3 environment is required (for example, Python 3.10).

2) Install Dependencies
In the backend project directory (the one that contains the app/ folder and run.py), create and activate a virtual environment, then install the required dependencies, including:

• Flask
• Flask-SQLAlchemy
• Flask-JWT-Extended
• Flask-Cors
• passlib
• requests

You can install them all using requirements.txt, for example: pip install -r requirements.txt

3) Check Database Configuration
In app/init.py, the backend will automatically create a library.db file in the project root directory and use SQLAlchemy to manage this database.
The database contains three tables: User, LibraryItem, and ApiCache.
When the application runs for the first time, create_app() will call db.create_all() to automatically create these tables, so no manual setup is needed.

4) Start the Backend Service
In the backend root directory, run:python run.py

---

II. Preparing the Frontend Environment (React + Vite)

1) Install Node.js
Node.js and npm are required (the version is not strict, as long as the Vite project can run normally).

2) Install Frontend Dependencies
Enter the frontend directory (which contains App.tsx, views/, components/, etc.): cd frontend npm install This installs React, Framer Motion, the Lucide icon library, and other dependencies.

3) Start the Frontend Development Server In the frontend directory, run:npm run dev Vite will start a development server at:http://localhost:3000

III. Simple Testing Flow

• Open the frontend address; you should first see the Login / Register page.
• Register a new account and log in with it.
• After logging in, the left Sidebar will show navigation (Home / Search / My Library / Recommend), and the bottom-right will show the database connection status.
• On the Home page, you should see Top Anime and Top Manga.
• On the Search page, enter a keyword and click Go to see search results and pagination.
• Click a title to go to the Details page; clicking a character in the Characters tab will open the character modal.
• On the Details page, click “Add to Library”; you should then see the title in My Library, where you can edit notes or delete it.
• After saving several titles, open the Recommend page to see recommendations generated from your Library.

File Overview

Backend (Flask)

app/

• init.py

  • Creates the Flask application and configures the database (library.db), JWT, and CORS.
  • Registers four blueprints: auth, jikan, library, recommend.
  • Automatically creates database tables on first startup.

• extensions.py

  • Defines global objects for db (SQLAlchemy), jwt (JWTManager), and cors (CORS) for use across modules.

• models.py

  • User: Stores user information (username, password hash). One user can have multiple LibraryItem.
  • LibraryItem: Stores saved items (mal_id, title, type, image_url, notes, user_id) and provides a to_dict method for frontend responses.
  • ApiCache: Stores cached external API responses (endpoint, data, last_updated).

app/api/

• auth.py

  • Provides /api/register and /api/login endpoints.
  • Handles user registration, login, and JWT token generation.

• jikan.py

  • Provides /api/search, /api/top/<media_type>, /api/character/<id>, /api/<media_type>/<id> endpoints.
  • Includes helper function fetch_and_cache, which checks ApiCache before requesting from Jikan API.

• library.py

  • Provides GET / POST for /api/library, and DELETE / PUT for /api/library/<mal_id>.
  • Handles reading, adding, deleting, and updating LibraryItem entries. All routes require login (jwt_required).

• recommend.py

  • Provides /api/recommend endpoint.
  • Analyzes the user's LibraryItem to determine preference (anime/manga), then fetches top titles from Jikan accordingly.

run.py

• Application entry point. Imports create_app from app and starts the Flask server (default port 5000).

---

Frontend (React)

src/App.tsx

• Main entry component of the frontend.
• Manages login state (token, username), current view (home / search / details / library / recommend), selected title details, and local Library data.
• Handles all interactions with the backend /api/library endpoints (load, add, delete, update notes), with fallback to local storage when the backend is unavailable.

src/components/Sidebar.tsx

• Left navigation bar showing the App logo, navigation buttons, and database connection status (connected / local mode).

src/components/MediaCard.tsx

• Displays an item card including cover image, title, year, type, score, and optional ranking.
• Used extensively on the Home page and Search page.

src/components/CharacterModal.tsx

• Character detail modal component.
• Shows large character image, English and Japanese names, favorites count, Japanese voice actor info, and full description.

src/views/AuthView.tsx

• Login / Register page.
• Provides username and password form, calls /api/login and /api/register, and returns token + username to App on success.

src/views/HomeView.tsx

• Home page view.
• Calls /api/top/anime and /api/top/manga and displays Top Anime and Top Manga in horizontal card lists.

src/views/SearchView.tsx

• Search page view.
• Provides search bar, type selection, sorting, genre filter, rating filter, year filter, and pagination.
• Calls /api/search and displays results; clicking a card opens the Details page.

src/views/DetailsView.tsx

• Item Details page.
• Loads detailed information, character list, and similar recommendations; includes “Add to Library” button.
• Clicking a character card calls backend character API and opens CharacterModal.

src/views/LibraryView.tsx

• User Library page.
• Displays all saved items, supports deletion and editing notes, and shows a warning when the backend is not connected (local mode fallback).

src/views/RecommendView.tsx

• Recommendation page.
• Calls /api/recommend and displays recommended items based on the user's Library.

Note: We leveraged AI software to learn how to interact with databases and APIs in python, and applied this knowledge to our project. On top of that, AI also assisted in generating the frontend interface, making the development process more efficient and seamless.