TPT Library

TPT Library is an Apache-2.0-licensed, open-source library management and discovery platform for public libraries.

It is designed as a web-first, API-first monorepo with PWA support, self-hosted deployment, and a single-library-first architecture that can grow into multi-library consortium deployments.

Capabilities

TPT Library is being built as a complete public library platform with:

Public catalog and discovery portal
Patron accounts and authentication
Staff and librarian dashboard
Catalog records and item copies
Barcode, QR, and manual circulation
Holds and reservations
Branches, locations, and shelves
Digital collections
Events and program registration
Fines, fees, manual payments, and optional Stripe payments
Acquisitions and purchase orders
Inter-library loan requests
Reports and exports
Email notifications
Import/export support for CSV, JSON, Dublin Core, and MARC-compatible workflows
OpenSearch-compatible faceted search
S3-compatible object storage through MinIO
Docker Compose deployment for local, VPS, and LAN hosting

Repository Structure

apps/
  web/        Public catalog and PWA
  admin/      Staff and librarian dashboard
  api/        NestJS API
  worker/     Background job worker
  docs/       Documentation site

packages/
  api-client/ Shared API client and types
  database/   Prisma schema, migrations, seed data
  domain/     Shared domain validators and types
  notifications/ Email and notification helpers
  payments/   Payment abstractions and Stripe adapter
  search/     Search client helpers
  ui/         Shared React UI components

docker/
  api/        API Dockerfile
  admin/      Admin Dockerfile
  docs/       Documentation Dockerfile
  nginx/      Reverse proxy templates
  web/        Web Dockerfile
  worker/     Worker Dockerfile

docs/
  api-documentation.md
  backup-restore.md
  contribution-workflow.md
  deployment.md

Quick Start

1. Install dependencies

pnpm install

2. Copy environment variables

cp .env.example .env

3. Start infrastructure

pnpm docker:up

This starts PostgreSQL, Redis, OpenSearch, MinIO, Mailpit, and the reverse proxy.

4. Generate the Prisma client and run migrations

pnpm db:generate
pnpm db:migrate:deploy
pnpm db:seed

5. Start the development platform

pnpm dev

Open the applications:

Public catalog: http://localhost:3000
Admin dashboard: http://localhost:3001
API: http://localhost:3002
API Swagger UI: http://localhost:3002/api-docs
Documentation app: http://localhost:3003
Reverse proxy: http://localhost

Default Demo Login

The seed script prints these demo credentials:

Patron
- Email: patron@example.local
- Password: password123
Librarian
- Email: librarian@example.local
- Password: password123
System administrator
- Email: admin@example.local
- Password: password123

Docker and Self-hosting

Build all application images:

pnpm docker:build

Start the full stack:

pnpm docker:up

Stop the stack without deleting volumes:

pnpm docker:down

View logs:

pnpm docker:logs

The reverse proxy routes:

/ to the public web app
/admin to the admin app
/api and /api/ to the API
/api-docs to API Swagger UI
/docs to the documentation app

See docs/deployment.md for production deployment, HTTPS, and environment configuration.

Seed, Reset, Backup, and Restore

Seed demo data:

pnpm seed

Reset the local database. This is destructive and requires confirmation:

pnpm reset -- --force

Create a PostgreSQL backup:

pnpm backup

Restore a PostgreSQL backup:

pnpm restore -- backups/postgres/tpt_library-YYYYMMDDHHmmssZ.sql

See docs/backup-restore.md for details.

API Documentation Generation

Generate the starter OpenAPI document for the documentation app:

pnpm docs:api

The generated file is written to apps/docs/public/openapi.json. Runtime Swagger UI is available at http://localhost:3002/api-docs.

See docs/api-documentation.md.

Development Commands

pnpm dev
pnpm build
pnpm typecheck
pnpm lint
pnpm test

Database commands:

pnpm db:generate
pnpm db:migrate:dev
pnpm db:migrate:deploy
pnpm db:seed
pnpm db:reset

Docker commands:

pnpm docker:up
pnpm docker:down
pnpm docker:build
pnpm docker:logs

Contribution Workflow

See docs/contribution-workflow.md for branching, review, API/database change, Docker, and pull request guidance.

License

Apache License 2.0.

tpt-library

Languages