LCC.Moe

Library of Congress Classification (LCC) lookup service powered by AI.

Overview

LCC.Moe is a web application that helps users find the appropriate Library of Congress Classification code for books. It uses AI to analyze book information and navigate through the LCC hierarchy to determine the most specific classification.

Features

• AI-Powered Classification: Uses LLM to intelligently classify books through the LCC hierarchy
• Real-time Progress: Watch the classification process as it navigates through each level
• Flexible Input: Submit any combination of title, author, ISBN, genre, keywords, summary, or abstract
• Privacy-Focused: No data storage, no cookies, no tracking
• Open Source: Fully transparent and auditable

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   SvelteKit 5   │────▶│    FastAPI      │────▶│   LLM API       │
│   Frontend      │◀────│    Backend      │◀────│   (OpenAI)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │  LCC JSON Data  │
                        │  (depth-4.json) │
                        └─────────────────┘

Technology Stack

• Frontend: SvelteKit 2.x with Svelte 5 (runes syntax)
• Backend: FastAPI 0.124+ with Python 3.13
• Web Server: Apache2 with mod_proxy
• Data: LCC classification data in JSON format
• AI: OpenAI-compatible API

Project Structure

lcc-moe/
├── backend/                 # FastAPI backend
│   ├── src/lcc_moe/        # Main application package
│   │   ├── api/            # API routes and models
│   │   ├── services/       # Business logic
│   │   └── utils/          # Utilities
│   ├── tests/              # Backend tests
│   └── pyproject.toml      # Python dependencies
├── frontend/               # SvelteKit frontend
│   ├── src/
│   │   ├── lib/           # Shared components and utilities
│   │   └── routes/        # Page routes
│   └── package.json       # Node dependencies
├── scripts/               # Deployment scripts
│   ├── deploy.sh          # Main deployment script
│   ├── setup-server.sh    # Server setup script
│   └── apache-lcc-moe.conf # Apache configuration
└── PLAN.md               # Detailed implementation plan

Quick Start

Prerequisites

• Python 3.13+
• Node.js 20+
• LCC JSON data file at /srv/lcc2json-data/depth-4.json
• OpenAI API key (or compatible API)

Development Setup

1. Clone the repository

   git clone https://github.com/spacecruft/lcc-moe.git
   cd lcc-moe
   

2. Setup Backend

   cd backend
   python3.13 -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   cp .env.example .env
   # Edit .env with your API key
   

3. Setup Frontend

   cd frontend
   npm install
   

4. Run Development Servers

   Terminal 1 (Backend):

   cd backend
   source .venv/bin/activate
   uvicorn lcc_moe.main:app --reload
   

   Terminal 2 (Frontend):

   cd frontend
   npm run dev
   

5. Open in Browser

   Navigate to http://localhost:5173

Configuration

Environment Variables

Create a .env file in the backend directory:

# LLM API Configuration
API_URL=https://api.openai.com/v1/chat/completions
API_MODEL=gpt-4
API_KEY=sk-your-api-key-here

# Application Configuration
DEBUG=true
LOG_LEVEL=DEBUG

# LCC Data
LCC_DATA_PATH=/srv/lcc2json-data/depth-4.json

# Server Configuration
HOST=127.0.0.1
PORT=8000

Deployment

Server Setup (Debian 13)

1. Run the server setup script:

   sudo ./scripts/setup-server.sh
   

2. Configure Apache:

   sudo cp scripts/apache-lcc-moe.conf /etc/apache2/sites-available/
   sudo a2ensite lcc-moe.conf
   sudo a2dissite 000-default.conf
   

3. Obtain SSL certificate:

   sudo certbot --apache -d lcc.moe -d www.lcc.moe
   

4. Deploy the application:

   sudo ./scripts/deploy.sh
   

API Endpoints

Health Check

GET /api/health

Classify Book (SSE Stream)

POST /api/classify
Content-Type: application/json

{
  "title": "Introduction to Algorithms",
  "author": "Thomas H. Cormen",
  "isbn": "978-0-262-03384-8"
}

Classify Book (Synchronous)

POST /api/classify/sync
Content-Type: application/json

{
  "title": "Introduction to Algorithms"
}

Security

• All inputs are sanitized using bleach and python-stdnum
• No user data is stored or logged (except in debug mode)
• No cookies are used
• HTTPS enforced in production
• Security headers configured in Apache

License

Apache License 2.0 - See LICENSE-apache.txt

Copyright © 2025, 2026 Jeff Moe