🎌 Paisen

Self-hosted MyAnimeList Manager

Paisen is a powerful, self-hosted anime management application that integrates with MyAnimeList to provide a comprehensive anime tracking experience. With its lightning-fast local database, 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

🗄️ 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

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

🚀 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)

⚙️ 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

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. Start Development Server

npm run dev

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

6. 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

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

🔧 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

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

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 data sources
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 MyAnimeList 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

👥 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 94 Commits
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

Folders and files

Latest commit

History

Repository files navigation

🎌 Paisen

📋 Table of Contents

✨ Features

🎯 Core Functionality

🗄️ Database & Performance

🗺️ Anime Mapping System

📸 Screenshots

🏠 Dashboard & Authentication

📚 Anime Management

📊 Analytics & Statistics

🚀 Quick Start

📋 Prerequisites

Required Software

Required Accounts

⚙️ Installation

1. Clone Repository

2. Install Dependencies

3. Environment Configuration

4. Database Setup

5. Start Development Server

6. Production Build

5. Build and Start

🔧 Configuration

MyAnimeList API Setup

Security Configuration

API Documentation

🧪 Testing

🔧 Troubleshooting

Common Issues and Solutions

MyAnimeList 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

📚 Documentation

🧪 Testing

🎨 UI/UX Improvements

🏷️ Commit Convention

📝 Issue Templates

📄 License

What this means:

🙏 Acknowledgments

🌟 Core Technologies

🔌 External Services

👥 Community

🎨 Design Resources

🎌 Made with ❤️ for the Anime Community

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages