🎌 Paisen

Self-hosted MyAnimeList Manager with Jellyfin Integration

Paisen is a powerful, self-hosted anime management application that seamlessly integrates MyAnimeList and Jellyfin to provide a comprehensive anime tracking experience. With its lightning-fast local database and intelligent cross-platform synchronization, Paisen transforms how you discover, track, and manage your anime collection.

✨ Features

🎯 Core Functionality

🔐 MyAnimeList Integration - Full OAuth2 authentication with secure token management
📚 Anime List Management - View, update, and organize your complete collection
🔍 Universal Search - Lightning-fast search across multiple databases
📊 Rich Analytics - Comprehensive statistics and watching pattern insights
👥 Multi-user Support - Isolated accounts with personal data protection

🎬 Media Server Integration

⚡ Real-time Sync - Automatic Jellyfin updates via webhooks
🧠 Smart Matching - Intelligent anime identification across platforms
📈 Progress Tracking - Seamless episode progress synchronization
📡 Server Monitoring - Real-time connection and activity status
📂 Library Management - Complete media collection overview

🗄️ Database & Performance

🚀 Lightning Speed - 90% faster than direct API calls
🔍 Full-text Search - Advanced indexing across all metadata
📱 Offline Support - Complete functionality without internet
🆔 Universal IDs - Cross-platform mapping (MAL, AniDB)
📊 Analytics Engine - Detailed statistics and performance metrics
🔄 Smart Caching - Intelligent data synchronization and updates

🗺️ Anime Mapping System

🔗 Offline Database - Uses manami-project/anime-offline-database for cross-platform mappings
🤖 Auto-Mapping - Automatic MAL to AniDB ID mapping suggestions
✅ User Confirmation - Review and confirm suggested mappings
✏️ Manual Override - Enter custom AniDB IDs when auto-mapping fails
📊 Mapping Statistics - Track confirmed vs suggested mappings
🔄 Periodic Updates - Regular offline database updates for latest mappings

📸 Screenshots

🏠 Dashboard & Authentication

Home Dashboard	User Registration

Main dashboard with activity overview and quick access	Secure user registration with validation

User Login	OAuth Authorization

Clean login interface with authentication	MyAnimeList OAuth integration

📚 Anime Management

Anime Library	Advanced Search

Comprehensive anime library with status, scores, and sorting	Powerful search with real-time results

Original Anime List

Original list view with status tracking

📊 Analytics & Statistics

Statistics Overview	Score Distribution

Detailed analytics and watching patterns	Score distribution and rating insights

🎬 Jellyfin Integration

Jellyfin Setup	Sync Management

Server configuration and monitoring	Real-time sync with progress tracking

🚀 Quick Start

# Clone the repository
git clone https://github.com/ninjashari/paisen.git
cd paisen

# Install dependencies
npm install

# Set up environment variables
cp .env.local.example .env.local
# Edit .env.local with your configuration

# Start development server
npm run dev

🎉 Open http://localhost:3000 to view Paisen

📋 Prerequisites

Before installing Paisen, ensure you have the following:

Required Software

Node.js 18.0+ (Download)
MongoDB 6.0+ (Installation Guide)
Git (Download)

Required Accounts

MyAnimeList Account (Create Account)
MyAnimeList API Application (Create App)

Optional (For Enhanced Features)

Jellyfin Server (Download) - For media server integration

⚙️ Installation

1. Clone Repository

git clone https://github.com/ninjashari/paisen.git
cd paisen

2. Install Dependencies

npm install

3. Environment Configuration

Create your environment file:

cp .env.local.example .env.local

Edit .env.local with your configuration:

# MyAnimeList API Configuration
MAL_CLIENT_ID=your_mal_client_id_here

# Security Keys (Generate secure random strings)
SECRET=your_32_character_secret_key_here
SYNC_KEY=your_secure_sync_key_here

# Database Configuration
MONGODB_URI=mongodb://localhost:27017/paisen

# Application URL
NEXTAUTH_URL=http://localhost:3000

# Optional: Jellyfin Configuration (can be set via UI)
JELLYFIN_SERVER_URL=http://your-jellyfin-server:8096
JELLYFIN_API_KEY=your_jellyfin_api_key

4. Database Setup

Start MongoDB service:

# On macOS (with Homebrew)
brew services start mongodb-community

# On Ubuntu/Debian
sudo systemctl start mongod

# On Windows
net start MongoDB

5. Initialize Anime Mapping Database

Set up the offline anime database for cross-platform mappings:

# Download and process the latest anime mappings
npm run db:init

This will:

Download the latest anime-offline-database from GitHub
Extract MAL to AniDB ID mappings
Store mappings in your local MongoDB database
Provide statistics on processed entries

6. Start Development Server

npm run dev

🎉 Your Paisen instance is now running at http://localhost:3000

7. Production Build

For production deployment:

# Ubuntu/Debian
sudo systemctl start mongod

# macOS with Homebrew
brew services start mongodb-community

# Windows
net start MongoDB

5. Build and Start

# Development mode
npm run dev

# Production mode
npm run build
npm start

🔧 Configuration

MyAnimeList API Setup

Visit MyAnimeList API
Click "Create ID" to create a new application
Fill in application details:
- App Type: Web
- App Name: Paisen (or your preferred name)
- App Description: Self-hosted anime management
- App Redirect URL: http://localhost:3000/oauth
- Homepage URL: http://localhost:3000/
- Commercial/Non-Commercial: Non-Commercial
Copy the Client ID to your .env.local file

Security Configuration

Generate secure keys for your installation:

# Generate SECRET (32 characters)
openssl rand -hex 16

# Generate SYNC_KEY (any secure string)
openssl rand -base64 32

🗺️ Anime Mapping Setup

Paisen uses the manami-project/anime-offline-database to create cross-platform mappings between MyAnimeList and AniDB. This enables enhanced compatibility and metadata enrichment.

Prerequisites

MongoDB running and connected
User account created and logged in
MyAnimeList data synchronized

Initial Database Setup

1. Initialize Offline Database

Run the initialization script to download and process the latest anime mappings:

# Download and process anime-offline-database
npm run db:init

This script will:

Download anime-offline-database-minified.json from manami-project
Extract MAL to AniDB mappings
Store mappings in your local MongoDB database
Show progress and statistics

2. Verify Database Status

Navigate to the Anime Mapping page to check database status:

Last update timestamp
Total mappings available
Processing statistics
Error status (if any)

Using the Anime Mapping Interface

1. Access Anime Mapping Page

Log in to your Paisen account
Navigate to "Anime Mapping" in the sidebar
View your anime list with mapping status

2. Understanding Mapping Status

Status	Description	Action Required
✅ Mapped	Anime has confirmed AniDB mapping	None
⚠️ Unmapped	No mapping found in offline database	Manual mapping required
🔍 Suggested	Automatic mapping found, needs confirmation	Review and confirm

3. Mapping Workflow

For Automatic Mappings:

Click "Map" button next to unmapped anime
Review suggested mapping from offline database
Confirm mapping if correct, or reject if incorrect
Mapping saved and marked as user-confirmed

For Manual Mappings:

Click "Map" button next to anime
No suggestion found - manual input required
Enter AniDB ID manually (find on anidb.net)
Save mapping - marked as manual mapping

4. Search and Filter

Use the filtering options to manage large anime lists:

Search by title or genre
Filter by watch status (watching, completed, etc.)
Filter by mapping status (mapped, unmapped)
Sort by title, status, episodes, or mapping status

Advanced Features

1. Periodic Updates

Keep your mapping database current:

# Manual update via script
npm run db:init

# Or use the web interface
# Navigate to Anime Mapping → Click "Update Database"

2. Database Status Monitoring

The interface shows important metrics:

Last Updated: When database was last refreshed
Total Mappings: Number of available mappings
Confirmed Mappings: User-confirmed and manual mappings
Update Status: Success/failure of last update

3. Mapping Sources

Paisen tracks mapping sources for transparency:

offline_database - From manami-project database
user_confirmed - User confirmed suggested mapping
manual - User manually entered mapping

API Endpoints

For developers and advanced users:

Endpoint	Method	Description
`/api/anime/mapping`	GET	Get mapping for MAL ID
`/api/anime/mapping`	POST	Create manual mapping
`/api/anime/mapping`	PUT	Confirm suggested mapping
`/api/anime/db-status`	GET	Get database status
`/api/anime/update-offline-db`	POST	Update offline database

Troubleshooting

❌ Database Update Failed

Error: Failed to download offline database

✅ Solution:

Check internet connection
Verify GitHub access (database hosted on GitHub)
Check disk space for database storage
Review logs for specific error details

❌ No Mappings Found

Warning: No mappings available for anime

✅ Solution:

Ensure offline database is initialized
Check if anime exists in manami-project database
Consider manual mapping for obscure/new anime
Verify MAL ID is correct

❌ Mapping Interface Not Loading

Error: Failed to load anime list

✅ Solution:

Ensure user is logged in
Check MyAnimeList data is synced
Verify database connection
Check browser console for errors

🎬 Jellyfin Integration

Prerequisites

Jellyfin Server 10.8.0 or higher
Admin access to Jellyfin server
Network connectivity between Paisen and Jellyfin

Setup Steps

1. Generate Jellyfin API Key

Open Jellyfin Dashboard → Advanced → API Keys
Click "+" to create new API key
Enter App Name: Paisen
Copy the generated API key

2. Configure in Paisen

Navigate to Jellyfin page in Paisen
Enter your server details:
- Server URL: http://your-jellyfin-server:8096
- API Key: (paste from step 1)
- User ID: (select from dropdown after connection)
Test Connection and Save Configuration

3. Optional: Webhook Setup

For real-time sync when episodes are watched:

In Jellyfin Dashboard → Plugins → Catalog
Install "Webhook" plugin if not already installed
Configure webhook:
- Webhook URL: http://your-paisen-url:3000/api/jellyfin/webhook
- Events: Playback Stop, Item Added
Save webhook configuration

Features

🔄 Automatic Sync - Updates when episodes are watched
📊 Progress Tracking - Episode progress syncs to MyAnimeList
🎯 Smart Matching - Intelligent anime identification
📈 Real-time Monitoring - Server status and activity tracking

🔌 API Documentation

Paisen provides a comprehensive REST API for integration with other applications.

API documentation coming soon.

🧪 Testing

Run the full test suite:

npm test

To run tests in watch mode:

npm test -- --watch

To initialize the database for testing:

npm run db:init

🔧 Troubleshooting

"Error: Could not connect to MongoDB"

Ensure your MongoDB server is running.
Verify that MONGODB_URI in .env.local is correct.

Common Issues and Solutions

MyAnimeList Issues

❌ Authentication Failed

Error: Invalid client credentials

✅ Solution:

Verify MAL_CLIENT_ID in .env.local
Check redirect URL in MAL app settings: http://localhost:3000/oauth
Ensure app is approved and active

❌ Token Expired

Error: Access token has expired

✅ Solution:

Navigate to OAuth page in Paisen
Re-authorize your MyAnimeList account
Check token expiry in user settings

Jellyfin Issues

❌ Connection Failed

Error: Unable to connect to Jellyfin server

✅ Solution:

Verify server URL format: http://server:8096
Check API key is valid and has permissions
Ensure network connectivity
Test server accessibility from browser

❌ Sync Issues

Error: Failed to sync anime data

✅ Solution:

Check anime library permissions
Verify metadata providers are configured
Ensure anime has proper MAL and AniDB mapping
Review sync logs for specific errors

❌ Webhook Not Working

Warning: Webhook events not received

✅ Solution:

Verify webhook URL is accessible: http://paisen:3000/api/jellyfin/webhook

Check Jellyfin webhook plugin configuration

Ensure correct events are selected

Test webhook manually

Database Issues

❌ Connection Error

Error: MongoNetworkError: connect ECONNREFUSED

✅ Solution:

Start MongoDB service: sudo systemctl start mongod

Check connection string in .env.local

Verify MongoDB is listening on correct port

Check disk space and permissions

❌ Performance Issues

Warning: Slow database queries

✅ Solution:

Check available disk space

Monitor MongoDB performance

Consider adding database indexes

Review query patterns in logs

General Issues

❌ Application Won't Start

Error: Cannot find module 'next'

✅ Solution:

Run npm install to install dependencies

Check Node.js version (requires 18+)

Clear node_modules and reinstall: rm -rf node_modules && npm install

Check for conflicting global packages

❌ Build Errors

Error: Build failed with errors

✅ Solution:

Check syntax errors in code

Verify all environment variables are set

Run npm run build to see detailed errors

Check for missing dependencies

Getting Help

1. Built-in Diagnostics

Jellyfin Page → Test Connection button

Jellyfin Info Page → Server Status and sync testing

Browser Console → Check for client-side errors

Network Tab → Monitor API requests and responses

2. Log Analysis

# Check application logs npm run dev # Development logs in console # Check MongoDB logs sudo tail -f /var/log/mongodb/mongod.log # Check system logs sudo journalctl -u mongod -f

3. Debug Mode

Enable debug logging in .env.local:

NODE_ENV=development DEBUG=paisen:*

4. Community Support

GitHub Issues: Report bugs and request features

Discussions: Ask questions and share ideas

Wiki: Detailed documentation and guides

When reporting issues, please include:

Operating system and version

Node.js and npm versions

Error messages and logs

Steps to reproduce the issue

Screenshots if applicable

🤝 Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or helping with testing, your contributions make Paisen better for everyone.

🚀 Quick Start for Contributors

# Fork the repository on GitHub # Clone your fork git clone https://github.com/YOUR_USERNAME/paisen.git cd paisen # Add upstream remote git remote add upstream https://github.com/ninjashari/paisen.git # Create a feature branch git checkout -b feature/your-feature-name # Make your changes and commit git add . git commit -m "feat: add your feature description" # Push to your fork and create a pull request git push origin feature/your-feature-name

📋 Contribution Guidelines

Code Style

Follow existing code style and conventions

Use meaningful variable and function names

Add comments for complex logic

Include JSDoc comments for functions

Run npm run lint before committing

Testing

Write tests for new features

Ensure all existing tests pass

Aim for high test coverage

Include both unit and integration tests

Documentation

Update README.md for new features

Add inline code comments

Update API documentation

Include screenshots for UI changes

Pull Request Process

Create an issue first to discuss major changes

Keep PRs focused on a single feature or bug fix

Write clear commit messages following conventional commits

Include tests for new functionality

Update documentation as needed

Request review from maintainers

🎯 Areas for Contribution

🐛 Bug Fixes

Fix reported issues

Improve error handling

Enhance stability

Performance optimizations

✨ New Features

Additional anime databases integration

Enhanced search capabilities

Mobile app development

Advanced analytics features

📚 Documentation

Improve setup guides

Add troubleshooting sections

Create video tutorials

Translate documentation

🧪 Testing

Increase test coverage

Add integration tests

Performance benchmarking

Cross-platform testing

🎨 UI/UX Improvements

Design enhancements

Accessibility improvements

Mobile responsiveness

User experience optimization

🏷️ Commit Convention

We use Conventional Commits:

feat: add new search functionality fix: resolve authentication token expiry issue docs: update installation guide test: add integration tests for Jellyfin sync refactor: improve database query performance style: fix code formatting issues

📝 Issue Templates

When creating issues, please use our templates:

🐛 Bug Report: For reporting bugs

✨ Feature Request: For suggesting new features

📚 Documentation: For documentation improvements

❓ Question: For asking questions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

What this means:

✅ Commercial use - You can use this software commercially

✅ Modification - You can modify the source code

✅ Distribution - You can distribute the software

✅ Private use - You can use this software privately

❌ Liability - The authors are not liable for any damages

❌ Warranty - No warranty is provided with this software

🙏 Acknowledgments

🌟 Core Technologies

Next.js - React framework for production

MongoDB - Document database for data storage

NextAuth.js - Authentication for Next.js

Bootstrap - CSS framework for responsive design

🔌 External Services

MyAnimeList - Primary anime database and user lists

Jellyfin - Open source media server integration

AniDB - Anime database for cross-platform mapping

👥 Community

Contributors - Everyone who has contributed code, documentation, or feedback

Beta Testers - Users who helped test and improve the application

Community Members - Active participants in discussions and support

🎨 Design Resources

Bootstrap Icons - Icon library

Unsplash - Stock photos for documentation

Community Screenshots - User-contributed interface examples

🎌 Made with ❤️ for the Anime Community

⭐ Star this project • 🐛 Report Issues • 💬 Join Discussions

Name		Name	Last commit message	Last commit date
Latest commit History 92 Commits
__tests__		__tests__
components		components
css		css
lib		lib
models		models
pages		pages
public		public
screens		screens
scripts		scripts
utils		utils
.cursorrules		.cursorrules
.env.local.example		.env.local.example
.gitignore		.gitignore
README.md		README.md
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
jsconfig.json		jsconfig.json
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json

ninjashari/paisen

Folders and files

Latest commit

History

Repository files navigation

🎌 Paisen

📋 Table of Contents

✨ Features

🎯 Core Functionality

🎬 Media Server Integration

🗄️ Database & Performance

🗺️ Anime Mapping System

📸 Screenshots

🏠 Dashboard & Authentication

📚 Anime Management

📊 Analytics & Statistics

🎬 Jellyfin Integration

🚀 Quick Start

📋 Prerequisites

Required Software

Required Accounts

Optional (For Enhanced Features)

⚙️ Installation

1. Clone Repository

2. Install Dependencies

3. Environment Configuration

4. Database Setup

5. Initialize Anime Mapping Database

6. Start Development Server

7. Production Build

5. Build and Start

🔧 Configuration

MyAnimeList API Setup

Security Configuration

🗺️ Anime Mapping Setup

Prerequisites

Initial Database Setup

1. Initialize Offline Database

2. Verify Database Status

Using the Anime Mapping Interface

1. Access Anime Mapping Page

2. Understanding Mapping Status

3. Mapping Workflow

4. Search and Filter

Advanced Features

1. Periodic Updates

2. Database Status Monitoring

3. Mapping Sources

API Endpoints

Troubleshooting

🎬 Jellyfin Integration

Prerequisites

Setup Steps

1. Generate Jellyfin API Key

2. Configure in Paisen

3. Optional: Webhook Setup

Features

🔌 API Documentation

🧪 Testing

🔧 Troubleshooting

Common Issues and Solutions

MyAnimeList Issues

Jellyfin Issues

Database Issues

General Issues

Getting Help

1. Built-in Diagnostics

2. Log Analysis

3. Debug Mode

4. Community Support

🤝 Contributing

🚀 Quick Start for Contributors

📋 Contribution Guidelines

Code Style

Testing

Documentation

Pull Request Process

🎯 Areas for Contribution

🐛 Bug Fixes

✨ New Features

Packages