Welcome to Mirenku Documentation

The Mirenku Way

Simple. Secure. No Bullshit.

Read the full philosophy →

About Mirenku

Mirenku is a desktop anime tracking application that respects your privacy and works offline. Born from frustration with modern trackers that require constant internet, harvest data, or push social features, Mirenku takes a different approach: it's just a tool that tracks anime.

What Makes Mirenku Different

• Truly Offline: Full functionality without internet. MAL sync is optional, not required.
• Actually Private: No telemetry, analytics, or tracking. We don't even know you exist.
• Just a Tool: No social features, achievements, or distractions. Track anime, nothing more.
• Completely Yours: Single executable, no installation, no accounts. Download and use forever.

Project History

Mirenku began in 2025 when existing anime trackers failed to meet simple requirements: work offline, respect privacy, and stay out of the way. Originally, and unoriginally, only called "Anime Tracker," it was rebranded to Mirenku in September 2025 with the addition of MyAnimeList integration.

The name Mirenku is a portmanteau of Japanese words: "miru" (見る - to watch) and "renku" (連句 - linked verses), representing watching your continuing anime story.

The Mascot

The turquoise fox-cat creature is also named Mirenku. With deliberately rough, pixelated edges that give it a handmade quality, the mascot embodies the app's philosophy: functional over flashy, honest rather than polished. The simple design reflects Mirenku's approach to software—no unnecessary refinement, just something that works.

Technology Stack

• Python 3.11+ - Core language
• Tkinter - Built-in UI framework (no dependencies)
• SQLite - Local database
• OAuth2 with PKCE - Secure MAL authentication
• Fernet + OS Keyring - Encrypted token storage

Development

Mirenku is developed by Aeturnis Development Labs LLC, a Wyoming-based software methodology laboratory. The project is source-available under the Prosperity Public License 3.0.0, which keeps it free for personal use forever.

Why Not MIT or GPL?

The Prosperity License protects The Mirenku Way. Under traditional open source licenses, companies could fork Mirenku and add everything we stand against: cloud storage, telemetry, ads, subscriptions, social features. They could turn our privacy-respecting tool into another data-harvesting platform.

The Prosperity License prevents this heresy. Mirenku stays free for personal use forever, but any commercial use requires permission—ensuring no one can corrupt Mirenku's principles for profit. This isn't about control; it's about protecting what Mirenku stands for.

Current Status

Version: 0.3.2 (September 2025)
Platform: Windows (Stable), macOS/Linux (Experimental)
License: Prosperity Public License 3.0.0
Repository: GitHub

Future Direction

Mirenku will remain focused on its core purpose: tracking anime simply and privately. Future updates will improve the tracking experience, add import options for other services, and expand platform support—but will never add telemetry, accounts, or social features.

For our complete philosophy and principles, read The Mirenku Way.

Installation

git clone https://github.com/Aeturnis-Development-Labs-LLC/mirenku.git
cd mirenku
pip install -r requirements.txt
python src/main.py

First Run Setup

When you launch Mirenku for the first time, you'll see a welcome dialog that helps you set up the application.

MyAnimeList Setup

Quick Connect

1. Click File → Connect to MAL or press Ctrl+Shift+M
2. Click "Connect to MAL" button in the dialog
3. Your browser opens to MyAnimeList authorization page
4. Log in and authorize Mirenku
5. You're automatically returned to the app - no codes to copy!

Security Features (Enhanced in v0.3.2)

• OAuth2 with PKCE: Industry-standard secure authentication with SHA256
• Encrypted Storage: Tokens encrypted with automatic key rotation (90 days)
• Token Refresh Buffer: 5-minute buffer prevents authentication failures
• Rate Limiting: Intelligent rate limiting with exponential backoff
• Security Audit Logging: Complete audit trail with privacy protection
• Error Sanitization: Prevents information leakage in error messages
• State Parameter Expiration: 10-minute expiration for enhanced security
• No Passwords: We never store or see your MAL password

Quick Start Guide

Adding Anime

Managing Your List

Library Management

Mirenku provides complete control over your anime library with full CRUD operations.

Adding Anime

• Manual Entry: Add anime with custom title, episode count, and status
• MAL Search: Search MyAnimeList database and import with metadata
• Quick Add: Press Ctrl+N for instant access
• Bulk Import: Import entire MAL user lists or JSON/CSV files

UI Enhancements (v0.3.2)

• Zebra Striping: Alternating row colors with Mirenku's teal palette
• Platform Fonts: Automatic font selection (Segoe UI, SF Pro, Noto Sans)
• Column Sorting: Click headers to sort by any field
• Synopsis Display: Improved 10-line display in detail dialog
• Auto-Refresh: Database monitoring with intelligent debouncing

Editing Entries

• Double-click any anime to open the edit dialog
• Right-click for context menu options
• Update title, episodes, status, score, and notes
• Set custom cover images from MAL or local files

Status Management

Organize your anime with five status categories:

• Watching: Currently airing or in progress
• Completed: Finished series
• On Hold: Temporarily paused
• Dropped: Discontinued watching
• Plan to Watch: Future viewing list

Episode Tracking

Track your viewing progress with intuitive controls and automatic synchronization.

Quick Updates

• +/- Buttons: Increment or decrement episode count with one click
• Direct Edit: Double-click the episode count to enter specific number
• Keyboard Control: Use arrow keys when selected
• Auto-Complete: Automatically marks as completed when reaching total episodes

Progress Tracking

• Visual progress bars show completion percentage
• Color-coded status indicators
• Sort by last updated to see recent activity
• Automatic timestamp updates on any change

Scoring System

• Rate anime on a 1-10 scale
• Optional scoring (can leave unrated)
• Syncs with MAL scoring if connected
• Sort by score to find favorites

MAL Synchronization

Seamless integration with MyAnimeList for backup and cross-device access.

OAuth2 Authentication

• Secure Connection: Industry-standard OAuth2 with PKCE
• No Passwords: Never stores or transmits your MAL password
• Auto-Refresh: Tokens refresh automatically in background
• Encrypted Storage: Three-tier encryption for credentials

Sync Options

• Push: Upload local changes to MAL
• Pull: Download MAL updates to local
• Full Sync: Bidirectional synchronization
• Selective Sync: Choose specific anime to sync
• Conflict Resolution: Manual review for conflicts

MAL Features

• Import entire MAL anime list
• Search MAL database directly
• Download cover art and metadata
• Update MAL list from Mirenku
• View MAL-specific fields (aired dates, studios, etc.)

Import/Export

Multiple formats for data portability and backup.

Import Options

• MAL User Import: Import any public MAL user's list
• JSON Import: Full data preservation including custom fields
• CSV Import: Compatible with spreadsheet applications
• Duplicate Detection: Smart merging of existing entries

Export Formats

• JSON Export: Complete backup with all metadata
• CSV Export: For analysis in Excel/Google Sheets
• Automatic Backups: Scheduled backup creation
• Selective Export: Export filtered lists only

Backup System

• One-click backup creation
• Timestamped backup files
• Restore from any backup point
• Backup validation before restore

Statistics

Track your anime watching habits with detailed statistics.

Overview Stats

• Total Anime: Complete library count
• Episodes Watched: Total episode count
• Status Breakdown: Anime per category
• Average Score: Your mean rating
• Time Watched: Estimated viewing time

Status Bar Information

• Current filter results count
• MAL connection status
• Offline queue count
• Last sync timestamp
• Auto-save indicator

Keyboard Shortcuts

OAuth Configuration

Advanced configuration options for MyAnimeList OAuth2 integration.

Authentication Method

• Localhost Callback: Mirenku uses a secure local server for OAuth callbacks
• Automatic Handling: Browser returns to app automatically after authorization
• No Manual Steps: No need to copy/paste authorization codes
• Port Selection: Automatically finds available port for callback server

Token Management

• Storage Location: Encrypted tokens in user data directory
• Auto-Refresh: Tokens refresh 24 hours before expiry
• Manual Refresh: Settings → MAL → Refresh Tokens
• Clear Tokens: Disconnect removes all stored credentials

Custom Client ID

For developers wanting to use their own MAL application:

1. Register at MAL API Config
2. Set redirect URL to: http://localhost:8888/oauth
3. Enter Client ID in Settings → MyAnimeList
4. Reconnect to MAL with new credentials

Offline Mode

Mirenku is designed to work completely offline with optional online features.

Offline Capabilities

• Full Functionality: All core features work without internet
• Local Database: SQLite stores all data locally
• Image Cache: Cover art cached for offline viewing
• No Phone Home: Zero telemetry or online requirements

Offline Queue System

• Automatic Queueing: Changes saved when MAL unreachable
• Queue Indicator: Status bar shows pending changes count
• Manual Processing: Tools → Process Offline Queue
• Conflict Resolution: Review conflicts when syncing

Network Detection

• Automatic network status detection
• Visual indicators for connection status
• Graceful degradation when offline
• Automatic retry for failed operations

Troubleshooting

Frequently Asked Questions

Building from Source

Prerequisites

• Python 3.11 or higher
• pip (Python package manager)
• Git (for cloning the repository)

Clone and Install

# Clone the repository
git clone https://github.com/Aeturnis-Development-Labs-LLC/mirenku.git
cd mirenku

# Install dependencies
pip install -r requirements.txt

# Run Mirenku
python src/main.py

Building Standalone Executable

# Install PyInstaller
pip install pyinstaller

# Build executable (Windows)
python build.py

# Or manually with PyInstaller
pyinstaller --onefile --windowed --icon=assets/mirenku.ico --name "Mirenku" src/main.py

Running Tests

# Run all tests
python -m pytest tests/

# Run with coverage report
python -m pytest tests/ --cov=src

# Run specific test file
python -m pytest tests/test_mal_sync_integration.py

Development Setup

For development, we recommend:

• Using a virtual environment (python -m venv venv)
• Installing development dependencies: pip install pytest pytest-cov
• Running python src/main.py directly for testing changes

Contributing

How to Contribute

Reporting Issues

• Check if the issue already exists on GitHub Issues
• Include your OS version, Python version, and Mirenku version
• Provide steps to reproduce the issue
• Include error messages or screenshots if applicable

Suggesting Features

• Open a discussion on GitHub Discussions
• Explain the use case and why it would benefit users
• Keep suggestions aligned with Mirenku's "Simple. Secure. No Bullshit." philosophy

Submitting Code

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Run tests: python -m pytest tests/
5. Commit with clear messages: git commit -m "Add: feature description"
6. Push to your fork: git push origin feature/your-feature
7. Open a Pull Request

Code Guidelines

• Style: Follow PEP 8 for Python code
• Tests: Add tests for new features
• Documentation: Update docstrings and README if needed
• Commits: Use clear, descriptive commit messages
• Simplicity: Keep it simple - no over-engineering

What We're Looking For

• Bug fixes
• Performance improvements
• UI/UX enhancements (within Tkinter's capabilities)
• MAL API feature additions
• Cross-platform compatibility fixes
• Documentation improvements

What We're NOT Looking For

• Complete rewrites in other languages/frameworks
• Cloud storage features
• User tracking or analytics
• Ads or monetization features
• Overly complex features that break simplicity

Join the Community

Chat with us on Discord before starting major changes to ensure alignment with project goals.

API Documentation

MyAnimeList Integration

Mirenku uses the official MyAnimeList API v2 for synchronization.

OAuth2 Flow

The app implements OAuth2 with PKCE for secure authentication:

1. User clicks "Connect to MAL"
2. Mirenku starts local callback server
3. Browser opens to MAL authorization
4. MAL redirects to localhost:8888/oauth with auth code
5. Tokens are encrypted and stored locally

API Endpoints Used

• GET /anime - Search for anime
• GET /users/@me/animelist - Fetch user's list
• PUT /anime/{id}/my_list_status - Update anime status
• DELETE /anime/{id}/my_list_status - Remove from list

Local Database Schema

SQLite database structure:

anime_list (
    id INTEGER PRIMARY KEY,
    mal_id INTEGER,
    title TEXT NOT NULL,
    episodes_watched INTEGER DEFAULT 0,
    total_episodes INTEGER,
    status TEXT,
    score INTEGER,
    notes TEXT,
    cover_image TEXT,
    last_updated TIMESTAMP
)

Internal Architecture

• UI Layer: Tkinter-based interface (src/ui/)
• Service Layer: Business logic (src/services/)
• Model Layer: Data models and database (src/models/)
• Utils: Configuration, logging, persistence (src/utils/)

Event System

Mirenku uses an event-driven architecture for UI updates:

• Database changes trigger UI refresh
• MAL sync operates on a queue system
• Offline changes are queued for later sync

Running Tests

Test Suite Overview

Mirenku has comprehensive test coverage with 150+ tests:

• Unit Tests: Individual component testing
• Integration Tests: MAL API and database integration
• End-to-End Tests: Full workflow testing

Running Tests

# Install test dependencies
pip install pytest pytest-cov pytest-mock

# Run all tests
python -m pytest tests/

# Run with verbose output
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_mal_service.py

# Run with coverage report
python -m pytest tests/ --cov=src --cov-report=html

# Run only unit tests (fast)
python -m pytest tests/ -m "not integration"

Test Structure

tests/
├── test_database.py          # Database operations
├── test_repository.py        # Data repository tests
├── test_service.py          # Business logic tests
├── test_mal_service.py      # MAL API tests
├── test_mal_oauth2_*.py     # OAuth implementation
├── test_integration_*.py    # Integration tests
├── test_end_to_end.py       # Full workflow tests
└── test_ui_*.py            # UI component tests

Writing Tests

When contributing, ensure your code includes tests:

def test_new_feature():
    """Test description of what should happen"""
    # Arrange
    service = AnimeService()
    
    # Act
    result = service.new_feature()
    
    # Assert
    assert result == expected_value

Continuous Integration

Tests run automatically on:

• Every push to main branch
• All pull requests
• Before releases

License

Mirenku is licensed under the Prosperity Public License 3.0.0.

Key License Terms

• ✅ Free for personal use forever
• ✅ 30-day commercial trial period
• ✅ Source code available for review and modification
• 💼 Commercial licenses available after trial period

Commercial Licensing

For commercial use beyond the 30-day trial, contact:

View the full license text: LICENSE on GitHub