Administrator Guide

Overview

BlueMoxon provides a full-featured admin interface for managing your rare book collection. Authenticated users can add, edit, and delete books, upload images, write analysis documents, and manage reference data like authors and publishers.

Authentication

BlueMoxon uses AWS Cognito for authentication. Users must sign in to access admin features like adding or editing books.

Signing In

1. Click the Sign In button in the navigation bar
2. Enter your email address and password
3. If you have MFA enabled, enter your verification code
4. Upon successful login, you'll see admin controls appear throughout the interface

Session Management

JWT tokens are stored securely and automatically refreshed. Sessions typically last 1 hour, with automatic refresh for up to 30 days of continuous use.

Adding Books

New books can be added through the web interface or via the REST API. The web form provides guided input with dropdowns for reference data and validation for required fields.

The Add Book form with basic information fields

Required Fields

Optional Fields

• Volumes: Number of volumes (default: 1)
• Binding Type: Morocco, calf, vellum, cloth, etc.
• Binder: Known binder (Rivière, Zaehnsdorf, etc.)
• Inventory Type: PRIMARY, EXTENDED, or FLAGGED
• Value Range: Low, mid, and high estimates in USD
• Purchase Price: Actual acquisition cost
• Purchase Date: When acquired
• Order Number: eBay/Etsy order reference
• Place of Purchase: eBay, Etsy, AbeBooks, etc.
• Notes: Free-form notes

Binding, condition, and valuation fields

Editing Books

Existing books can be edited by clicking the Edit button on any book detail page. All fields are editable, and changes are saved immediately when you click Save.

The Edit Book form with pre-populated fields

Edit Actions

• Edit Metadata: Modify any book field
• Update Status: Change delivery status (IN_TRANSIT, ON_HAND)
• Edit Analysis: Open the markdown editor for analysis documents
• Manage Images: Add, remove, or reorder images

Deleting Books

Books can be permanently deleted from the book detail page. This action requires confirmation and cannot be undone.

1. Navigate to the book detail page
2. Click the Delete button (red, typically in the action bar)
3. Confirm the deletion in the modal dialog
4. The book and all associated data will be permanently removed

Status Tracking

Books can have different delivery statuses to track acquisitions from purchase to arrival.

Updating Status via API

curl -X PATCH "https://api.bluemoxon.com/api/v1/books/{id}/status?status=ON_HAND" \
  -H "X-API-Key: $BMX_API_KEY"

Acquisitions Dashboard

The Acquisitions Dashboard is your command center for tracking book purchases from discovery through delivery. Access it from Admin → Acquisitions in the navigation.

Acquisition Workflow

The typical workflow follows this progression:

1. Discover: Find a listing on eBay, Etsy, or another marketplace
2. Import: Paste the URL into the Acquisitions Dashboard to auto-populate details
3. Evaluate: Review the AI-generated investment scores and valuation estimate
4. Purchase: If the scores warrant, complete the purchase and update status to "In Transit"
5. Receive: When the book arrives, mark as "On Hand" and convert to collection entry

eBay Import

The eBay Import feature lets you paste a listing URL to automatically extract title, price, seller, images, and other metadata. This eliminates manual data entry and preserves the original listing information.

How to Import

1. Copy the eBay listing URL from your browser
2. Navigate to Admin → Acquisitions
3. Click Import from eBay
4. Paste the URL and click Import
5. Review the extracted data and adjust if needed
6. Save to add to your Watchlist or directly to In Transit

Extracted Fields

Supported Formats

The importer accepts various eBay URL formats:

• https://www.ebay.com/itm/123456789
• https://www.ebay.co.uk/itm/123456789
• https://ebay.com/itm/title-slug/123456789

Investment Scoring

Every acquisition is automatically scored at import time using a proprietary algorithm that considers binding quality, author significance, collection fit, and purchase economics.

Investment Grade (0-100)

The Investment Grade measures the overall investment potential of an acquisition. Higher scores indicate better value propositions based on multiple factors.

Strategic Fit (0-7)

Strategic Fit measures how well an acquisition aligns with your collection focus. This score considers your target author list, preferred publishers, and binding priorities.

Scoring Factors

• +2: Priority 1 target author
• +1: Priority 2-3 target author
• +1: Tier 1 publisher (Moxon, Pickering, etc.)
• +1: Premium binding (full morocco, signed binder)
• +1: Victorian era poetry (collection focus)
• +1: Multi-volume set
• +1: Extra-illustrated or unique features

Wayback Archive

The Wayback Archive feature automatically saves a snapshot of eBay listings to the Internet Archive. This preserves the original listing details, images, and pricing for future reference even after the listing expires or is removed.

Why Archive Listings?

• Provenance Documentation: Preserve the original listing as purchase evidence
• Price Verification: Original asking price for insurance or resale records
• Condition Records: Seller's description at time of purchase
• Image Backup: Original images even if eBay removes them

How It Works

1. When you import an eBay listing, the system submits the URL to the Wayback Machine
2. The archive URL is stored with the acquisition record
3. Access the archived version anytime from the acquisition details
4. Archive links are also preserved when converting to collection entries

Viewing Archived Listings

Click the View Archive link on any acquisition to open the preserved listing in a new tab. The archive shows the listing exactly as it appeared at capture time.

Shipment Tracking

Track your in-transit acquisitions with automatic carrier detection and real-time status updates. Add a tracking number to any book and BlueMoxon generates the tracking URL automatically.

Adding Tracking Information

1. Navigate to the book detail page for an in-transit acquisition
2. Click Add Tracking in the status section
3. Enter the tracking number - the carrier is detected automatically
4. Click Save to store the tracking information
5. Click the tracking link to open the carrier's tracking page

Supported Carriers

Tracking Status

Click Refresh Status to update the tracking status from the carrier. Status values include: pending, in_transit, out_for_delivery, delivered, exception.

Uploading Images

Each book can have multiple images. The first image (or designated primary) appears as the thumbnail in collection views.

1. Navigate to the book detail page
2. Click Add Images in the image section
3. Select one or more image files (JPG, PNG supported)
4. Images are uploaded to S3 and served via CloudFront CDN
5. The page refreshes to show newly uploaded images

Reordering Images

Image order can be changed using drag-and-drop or the Reorder button. The first image becomes the primary thumbnail.

Book detail page showing Edit, Delete, Add Images, and Reorder buttons

Image Actions

• Reorder: Drag images to change their display order
• Set Primary: Click to make an image the main thumbnail
• Delete: Remove individual images
• View Full Size: Click to open in lightbox gallery

Image Gallery

Clicking any image opens a full-screen lightbox with navigation controls. Supports keyboard navigation (arrow keys) and swipe gestures on mobile.

Full-screen image gallery with thumbnail navigation

Analysis Editor

Each book can have a detailed analysis document written in Markdown. The editor provides live preview and supports the full Napoleon Framework for rare book evaluation.

Rendered analysis document with professional valuation report format

Analysis Sections

• Executive Summary: Brief overview and significance
• Provenance: History and previous ownership
• Physical Description: Binding, paper, condition details
• Valuation: Market analysis and comparable sales
• Recommendation: BUY / PASS / CONDITIONAL BUY

Async Analysis Generation

For complex analyses that require extended processing time, BlueMoxon uses asynchronous generation via SQS queues. This allows analyses to run without timeout limits and provides real-time progress updates.

How Async Analysis Works

1. Click Generate Analysis on a book detail page
2. Select your preferred model (Sonnet for speed, Opus for quality)
3. The job is submitted to the analysis queue
4. Monitor progress in real-time - status updates every few seconds
5. When complete, the analysis appears automatically

Job Status

Model Version Tracking

Each analysis records the AI model version used (e.g., "claude-sonnet-4-20250514"). This allows you to track which model generated each analysis and compare results over time as models improve.

Markdown Formatting

The analysis editor supports GitHub-flavored Markdown with tables, code blocks, and more.

# Book Title

## Executive Summary
Brief overview of the book's significance...

## Physical Description
| Attribute | Value |
|-----------|-------|
| Binding | Full morocco |
| Condition | Very good |

## Valuation
- **Low estimate:** $200
- **Mid estimate:** $275
- **High estimate:** $350

Entity Management

The Reference Data tab in the Admin Config provides a full CRUD interface for managing authors, publishers, and binders. Access it from Config → Reference Data.

Preferred Entities

Mark entities as "preferred" to give books by that author, publisher, or binder a +10 point bonus in investment scoring. Use this for collection priorities that don't fit into the tier system.

Tier Classifications

Authors

Authors are managed as reference data and can be selected when adding or editing books. New authors are created automatically when entering a new name.

Author Fields

• Name: Full name (e.g., "Charles Dickens")
• Birth Year: Optional birth year
• Death Year: Optional death year
• Era: Victorian, Romantic, Georgian, etc.
• Tier: Tier 1, 2, or 3 classification
• Preferred: Mark for +10 scoring bonus
• Priority Score: Numeric priority for target acquisitions

Publishers

Publishers include both the company name and location. Common formats include "Chapman and Hall, London" or "Scribner's, New York".

Publisher Fields

• Name: Publisher name (e.g., "John Murray")
• Founded: Year founded (optional)
• Description: Notes about the publisher
• Tier: Tier 1, 2, or 3 classification
• Preferred: Mark for +10 scoring bonus

Binders

For books with identified bindings by known binderies. Common examples include Rivière, Zaehnsdorf, Sangorski & Sutcliffe, and Root & Son.

Binder Fields

• Name: Short name (e.g., "Rivière")
• Full Name: Complete name (e.g., "Rivière & Son")
• Authentication Markers: How to identify genuine bindings
• Tier: Tier 1, 2, or 3 classification
• Preferred: Mark for +10 scoring bonus

Entity Reassignment

Use reassignment to merge duplicate or variant entities. All books are transferred from the source entity to the target, then the source is deleted.

Common Use Cases

• Merge duplicates: "W.M. Thackeray" → "William Makepeace Thackeray"
• Consolidate variants: "Riviere" → "Rivière & Son"
• Fix typos: "Chapmn and Hall" → "Chapman and Hall"

How to Reassign

1. Navigate to Config → Reference Data
2. Select the entity type tab (Authors, Publishers, or Binders)
3. Find the source entity (the one to be merged away)
4. Click the Reassign button (↔️ icon)
5. Select the target entity from the dropdown
6. Confirm the operation

Dashboard Statistics

The dashboard provides real-time statistics about your collection.

Dashboard with collection statistics and quick actions

Available Statistics

• Total Books: Count of all books in collection
• Total Images: Number of uploaded images
• Total Value: Sum of mid-range valuations
• By Inventory Type: Primary, Extended, Flagged breakdown
• By Status: On Hand vs. In Transit
• Recent Additions: Latest books added

Filtering & Search

The collection browser supports multiple filter criteria and full-text search.

Collection browser with filters, search, and sort controls

Filter Options

• Search: Full-text search across title, author, notes
• Author: Filter by specific author
• Publisher: Filter by publisher
• Binding Type: Morocco, calf, vellum, cloth, etc.
• Inventory Type: PRIMARY, EXTENDED, FLAGGED
• Status: ON_HAND, IN_TRANSIT, SOLD
• Date Range: Filter by publication date

Sort Options

• Title (A-Z, Z-A)
• Author (A-Z, Z-A)
• Publication Date (oldest first, newest first)
• Date Added (oldest first, newest first)
• Value (low to high, high to low)

User Roles

BlueMoxon supports different user roles through Cognito groups. Roles determine what actions users can perform.

Cognito Administration

User accounts are managed through AWS Cognito. Admin users can manage other users via the AWS Console or Cognito APIs.

Managing Users in AWS Console

1. Navigate to the AWS Console and open Cognito
2. Select the BlueMoxon User Pool
3. Click on "Users and groups" in the left sidebar
4. Create, edit, or disable user accounts as needed
5. Assign users to groups (Admin, Editor, Viewer) to set permissions

Adding Users to Groups

1. In Cognito User Pool, select the "Groups" tab
2. Click on the desired group (e.g., "Admin")
3. Click "Add users to group"
4. Select the user(s) to add
5. The user's role takes effect on their next sign-in

Common User Management Tasks

• Reset Password: Use "Reset password" action to send reset email
• Disable Account: Toggle user status to disable login
• Enable MFA: Configure MFA settings in User Pool settings
• View Sign-in History: Check user attributes and last login

# List users in the pool
aws cognito-idp list-users --user-pool-id us-west-2_XXXXX

# Add user to admin group
aws cognito-idp admin-add-user-to-group \
  --user-pool-id us-west-2_XXXXX \
  --username user@example.com \
  --group-name Admin

Garbage Image Review

BlueMoxon's AI automatically flags images that don't appear to be book photographs. The Maintenance tab lets you review these flagged images and confirm or override the classification.

What Gets Flagged

• Seller logos: Watermarks and branding images
• Screenshots: Computer or phone screenshots
• Text images: Scanned text or certificates
• Unrelated photos: Non-book images in listings

Reviewing Flagged Images

1. Navigate to Config → Maintenance
2. View the list of images flagged as garbage
3. For each image, choose to Confirm (delete) or Keep (override)
4. Confirmed garbage images are permanently deleted

Orphan Cleanup

The Maintenance tab identifies and helps clean up orphaned database records - data that has lost its parent relationship.

Types of Orphans

Running Cleanup

1. Navigate to Config → Maintenance
2. Click Detect Orphans to scan the database
3. Review the list of orphaned records
4. Click Cleanup Orphans to remove them

Victorian Dark Mode

BlueMoxon features an elegant dark theme inspired by Victorian aesthetics. Deep burgundy backgrounds, parchment-colored text, and gold accents create a distinguished reading experience.

Enabling Dark Mode

• Toggle: Click the moon/sun icon in the navigation bar
• System sync: Automatically follows your OS preference
• Persistence: Your choice is saved and applied on every visit

Color Palette