checkscanner

Python package for the check scanner backend. Manages connections to Magtek and RDM check scanning devices, extracts MICR data and check images, and serves them through a JWT-authenticated REST API.

Requirements

• Python 3.6+
• SQLite3
• pip 21.3.1+ (required on Python 3.6 to resolve pre-built wheels)

Installation

Ensure pip is up to date before installing:

pip install --upgrade pip

Then install the package from PyPI:

pip install checkscanner

Or from the source tree:

cd server
pip install .

For development (changes take effect without reinstalling):

pip install -e .

Building the Frontend

The frontend must be built and bundled into the package before installing. Run this once from the source tree (requires Node.js):

checkscanner build
pip install .   # reinstall to pick up the bundled frontend

In development with an editable install, checkscanner build copies the output directly into src/checkscanner/static/ so it takes effect immediately without reinstalling.

Usage

The package installs two commands. Run them from your project directory — config files and the database are created there.

# Start the API server (serves UI at http://localhost:8000/).
# Runs first-time setup automatically if needed.
checkscanner

# Open the interactive admin console
checkscanner-cli

checkscanner also accepts subcommands (run checkscanner --help or checkscanner <command> --help for details):

checkscanner server [options]   # Same as no arguments; see `checkscanner server --help`
checkscanner setup [-i]         # Create anything missing: config/, server.db, admin user (-i: edit config first)
checkscanner status             # Show config, database and connection status
checkscanner admin              # Same as checkscanner-cli
checkscanner build              # Build the frontend and bundle it into the package (source tree only)

checkscanner user list|add|passwd|delete
checkscanner profile list|add|delete
checkscanner config show|edit|rotate-keys
checkscanner token <username>[:<password>]   # or -u <username> [-p <password>]

Server options can also be passed directly, e.g. checkscanner --port 9000.

First-Time Setup

checkscanner setup (also runs automatically before the server and admin console start) creates:

Admin Console

checkscanner-cli opens an arrow-key menu for managing the server:

• View server status
• List, add and delete users; reset passwords
• List, add and delete check scanner profiles
• Edit config and regenerate auth keys
• Get a bearer token for API testing
• Start the server, optionally restarting it automatically when it stops

Every menu action is also available as a checkscanner subcommand for scripting.

API

Swagger UI is available at http://localhost:8000/docs when the server is running.

Supported Devices

Project Structure

src/
└── checkscanner/
    ├── app.py                    # Bottle API server
    ├── admin_console.py          # Interactive admin CLI
    ├── active_scanners.py        # In-memory scanner connection registry
    ├── auth.py                   # Password hashing and JWT verification
    ├── ftp_server.py             # FTP server for Magtek image uploads
    ├── debugger.py               # Colored terminal logging
    ├── bottle/                   # Vendored Bottle framework + plugins
    ├── resources/                # REST resource handlers
    ├── check_scanner_handlers/   # Device-specific connection handlers
    ├── static/                   # Bundled frontend (populated by `checkscanner build`)
    ├── swagger/                  # Bundled Swagger UI
    └── data/                     # Bundled assets (schema, font, API spec)

Dependencies