Codex Librarium

A comprehensive web application for tracking your progress through the vast Warhammer 40,000 Black Library collection. Built with Next.js 15, TypeScript, and Supabase.

Features

📚 Extensive Book Collection

76+ complete series with 440 books total
85 standalone novels
101 novellas
137 anthologies and collections
763 unique books across all categories
Major series including:
- The Horus Heresy (54 books)
- Siege of Terra (8 books)
- Dawn of Fire (9 books, ongoing)
- Gaunt's Ghosts (16 books)
- Eisenhorn, Ravenor, and Bequin trilogies
- Ultramarines, Night Lords, Space Wolves, and more
- Xenos-focused series: Path of the Eldar, Twice-Dead King, Phoenix Lords

🎯 Smart Organization

Four Book Categories - Separate navigation for Series, Singles, Novellas, and Anthologies
Multiple Sorting Options per Category - Each category supports browsing:
- By Series (Series only) - Follow Black Library publication order
- By Name - Alphabetically sorted complete catalog
- By Tags - Find books by themes (e.g., "Primarchs", "Siege", "Investigation")
- By Factions - Filter by your favorite armies and factions
Pagination - 20 items per page for easy browsing
Search Functionality - Quick filtering within tags and factions views

📊 Progress Tracking

Three reading states: Unread, Reading, Completed
Tabbed Dashboard - Separate dashboards for Series, Singles, Novellas, and Anthologies
Visual progress indicators and completion rates
Statistics for each category (Total, Completed, Reading, Unread)
Collapsible Sections - Currently Reading and Completed Books sections with expand/collapse functionality
Rating and Notes - Add ratings (1-5 stars) and personal notes for Singles, Novellas, and Anthologies
Real-time sync across all your devices

🎨 Premium UI/UX

Warhammer-themed dark interface with Imperial Gold accents
Detailed book modals with all metadata
Responsive design for desktop and mobile
Smooth animations and transitions

🔐 Authentication & Security

Google OAuth via Supabase Auth
Row-level security for user data
Admin-only import functionality
Secure API endpoints

📝 Book Requests

User Requests - Any authenticated user can request books to be added to the library
Request Management - Four status categories:
- Requests (Pending) - New requests awaiting admin review
- Approved - Requests accepted and fulfilled
- Waitlist - Requests acknowledged but not yet ready to add
- Refused - Requests rejected with admin-provided reasons
Filtering - Sort requests by newest or oldest
Admin-Only Status Changes - Only admins can move requests between statuses
Refusal Comments - Required explanations when refusing requests, with edit tracking

⚙️ Admin Features

JSON-based book import system with file selection
Support for importing Series, Singles, Novellas, and Anthologies
Automatic tag and faction normalization
Folder-based organization (_meta folders) for easy management
Real-time updates to canonical tag/faction lists across all categories
Selective import (choose specific files to import)
Book request management with status updates and refusal comments

Tech Stack

Framework: Next.js 15 (App Router)
Language: TypeScript
Database: Supabase (PostgreSQL)
Authentication: Supabase Auth (Google OAuth)
Styling: Tailwind CSS
UI Components: Custom design system
Deployment Ready: Vercel-optimized

Getting Started

Prerequisites

Node.js 18+
npm/yarn/pnpm/bun
Supabase account

Installation

Clone the repository:

git clone https://github.com/yourusername/codex-librarium.git
cd codex-librarium

Install dependencies:

npm install

Set up environment variables:

cp .env.example .env.local

Edit .env.local and add your Supabase credentials:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
ADMIN_EMAILS=your-admin-email@example.com

Run the development server:

npm run dev

Open http://localhost:3000

Project Structure

├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   │   ├── books/         # Series books API
│   │   ├── singles/       # Singles API
│   │   ├── novellas/      # Novellas API
│   │   ├── anthologies/   # Anthologies API
│   │   ├── reading/       # Reading progress APIs
│   │   │   ├── route.ts   # Series progress (GET/POST)
│   │   │   ├── singles/   # Singles progress (GET/POST)
│   │   │   ├── novellas/  # Novellas progress (GET/POST)
│   │   │   └── anthologies/ # Anthologies progress (GET/POST)
│   │   ├── requests/      # Book requests APIs
│   │   │   ├── route.ts   # List/create requests (GET/POST)
│   │   │   └── [id]/      # Update/delete request (PATCH/DELETE)
│   │   └── import/        # Import system APIs
│   ├── dashboard/         # Dashboard pages
│   │   ├── page.tsx       # Series dashboard
│   │   ├── singles/       # Singles dashboard
│   │   ├── novellas/      # Novellas dashboard
│   │   ├── anthologies/   # Anthologies dashboard
│   │   └── requests/      # Book requests dashboard
│   ├── import/            # Admin import page
│   ├── order/             # Book browsing pages
│   │   ├── series/        # Series books
│   │   │   ├── page.tsx   # Redirect to /series
│   │   │   ├── series/    # Browse by series
│   │   │   ├── name/      # Browse by name
│   │   │   ├── tags/      # Browse by tags
│   │   │   └── factions/  # Browse by factions
│   │   ├── singles/       # Single novels
│   │   │   ├── page.tsx   # Redirect to /name
│   │   │   ├── name/      # Browse by name
│   │   │   ├── tags/      # Browse by tags
│   │   │   └── factions/  # Browse by factions
│   │   ├── novellas/      # Novellas
│   │   │   ├── page.tsx   # Redirect to /name
│   │   │   ├── name/      # Browse by name
│   │   │   ├── tags/      # Browse by tags
│   │   │   └── factions/  # Browse by factions
│   │   └── anthologies/   # Anthologies
│   │       ├── page.tsx   # Redirect to /name
│   │       ├── name/      # Browse by name
│   │       ├── tags/      # Browse by tags
│   │       └── factions/  # Browse by factions
│   └── auth/              # Authentication callbacks
├── components/            # React components
│   ├── AppLayout.tsx      # Main layout wrapper
│   ├── BookDetailsModal.tsx
│   ├── DashboardTabs.tsx  # Dashboard category tabs
│   ├── OrderTabs.tsx      # Sorting tabs
│   ├── Navbar.tsx
│   └── SeriesView.tsx
├── lib/                   # Utilities and types
│   ├── supabase/          # Supabase client setup
│   ├── design-system.ts   # Theming and styles
│   └── types.ts           # TypeScript definitions
├── data/                  # Book data
│   ├── series/            # Series JSON files
│   │   └── _meta/         # tags.json, factions.json
│   ├── singles/           # Singles JSON files
│   │   └── _meta/         # tags.json, factions.json
│   ├── novellas/          # Novellas JSON files
│   │   └── _meta/         # tags.json, factions.json
│   └── anthologies/       # Anthologies JSON files
│       └── _meta/         # tags.json, factions.json
├── supabase/              # Database migrations
│   └── migrations/        # SQL migration files
└── .claude/               # Documentation
    ├── DESIGN_SYSTEM.md
    ├── DATABASE.md
    ├── API_ENDPOINTS.md
    └── AUTHENTICATION.md

Database Setup

Option 1: Using Supabase Dashboard (Recommended for new projects)

Create a new Supabase project at https://supabase.com/dashboard
Go to SQL Editor in your Supabase dashboard
Run supabase/migrations/004_complete_fresh_schema.sql - Creates all tables, indexes, and RLS policies
Run supabase/migrations/005_add_book_requests.sql - Adds book requests feature
In Authentication → Providers, enable Google OAuth with your credentials

Option 2: Using Supabase CLI

npx supabase db push

The database includes:

Book Tables: series, series_books, singles, novellas, anthologies
Reading Progress Tables: reading_progress_series_books, reading_progress_singles, reading_progress_novellas, reading_progress_anthologies
Book Requests Table: book_requests - User-submitted book requests with admin management
Row Level Security (RLS) on all tables
Indexes for optimal query performance

See supabase/migrations/004_complete_fresh_schema.sql for the main schema and 005_add_book_requests.sql for the book requests feature.

Adding Books

Books are stored as JSON files in four category directories:

data/series/ - Series with books
data/singles/ - Standalone novels
data/novellas/ - Novellas
data/anthologies/ - Anthologies and collections

To add books:

Create a new JSON file in the appropriate category folder
Follow the schema for that category
Tags and factions will auto-normalize against canonical lists in _meta/ folders
Validate your changes:

npm run validate-data

This script checks for:

Missing IDs
Duplicate IDs within each table
Overlapping IDs between tables (warning only)

For admin access, use the /import page to selectively import JSON files.

Documentation

Comprehensive documentation is available in the .claude/ directory:

DESIGN_SYSTEM.md - Colors, typography, component patterns
DATABASE.md - Schema, RLS policies, queries
API_ENDPOINTS.md - API reference and examples
AUTHENTICATION.md - Auth flow and security
PROJECT_STRUCTURE.md - Architecture overview
ADDING_BOOKS.md - Book import guide

Deployment

Deploy to Vercel

Push your code to GitHub
Import the repository in Vercel
Add environment variables in Vercel dashboard
Deploy!

Environment Variables for Production

Make sure to set these in your Vercel dashboard:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY (for admin imports)
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
ADMIN_EMAILS (comma-separated list)

Contributing

Contributions are welcome! To add new book series:

Fork the repository
Create a new series JSON file following the schema
Test locally
Submit a pull request

License

This is a personal project for tracking Warhammer 40,000 book collections. All Warhammer 40,000 intellectual property belongs to Games Workshop.

Acknowledgments

Black Library for the incredible Warhammer 40,000 book collection
Games Workshop for the Warhammer 40,000 universe
The community for keeping track of reading orders

In the grim darkness of the far future, there are only books to track.

Name		Name	Last commit message	Last commit date
Latest commit History 91 Commits
.claude		.claude
app		app
components		components
data		data
lib		lib
public		public
scripts		scripts
supabase/migrations		supabase/migrations
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
middleware.ts		middleware.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Codex Librarium

Features

📚 Extensive Book Collection

🎯 Smart Organization

📊 Progress Tracking

🎨 Premium UI/UX

🔐 Authentication & Security

📝 Book Requests

⚙️ Admin Features

Tech Stack

Getting Started

Prerequisites

Installation

Project Structure

Database Setup

Option 1: Using Supabase Dashboard (Recommended for new projects)

Option 2: Using Supabase CLI

Adding Books

Documentation

Deployment

Deploy to Vercel

Environment Variables for Production

Contributing

License

Acknowledgments

About

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Codex Librarium

Features

📚 Extensive Book Collection

🎯 Smart Organization

📊 Progress Tracking

🎨 Premium UI/UX

🔐 Authentication & Security

📝 Book Requests

⚙️ Admin Features

Tech Stack

Getting Started

Prerequisites

Installation

Project Structure

Database Setup

Option 1: Using Supabase Dashboard (Recommended for new projects)

Option 2: Using Supabase CLI

Adding Books

Documentation

Deployment

Deploy to Vercel

Environment Variables for Production

Contributing

License

Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages