Folio

Nx monorepo containing:

• API: Express + PostgreSQL
• Web: Vite + React
• Mobile: Expo

Documentation

Full documentation for users and developers is published at:

https://mnaimfaizy.github.io/folio/

• User Guide — non-technical setup and usage
• Developer Guide — architecture, API patterns, contributing

To run the docs site locally:

cd docs-site
npm install
npm run docs:dev

---

• Profile overview + behavior matrix: docs/USAGE_PROFILES.md
• Single-user practical guide: docs/deployment/SINGLE_USER_MINIMAL_SETUP.md
• Public showcase practical guide: docs/deployment/PUBLIC_SHOWCASE_SETUP.md

Contributor workflow

• Feature implementation and code organization guide: docs/FEATURE_DEVELOPMENT_GUIDE.md

Prerequisites

• Node.js 22.x (see package.json engines)
• Yarn 1.x (repo uses workspaces)
• Docker (optional, for local Postgres + PgAdmin + Mailhog)

Install

yarn

Local dev (recommended)

1) Start dev infrastructure (recommended)

This brings up Postgres + PgAdmin + Mailhog for local development.

yarn docker:up

Services:

• Postgres: localhost:5432 (db folio, user folio, password folio)
• Mailhog UI: http://localhost:8025 (SMTP on localhost:1025)
• PgAdmin: http://localhost:5050 (email admin@folio.com, password admin)

Postgres is initialized from:

• docker/postgres/init/001_schema.sql
• docker/postgres/init/002_seed.sql

Seeded users:

• admin@folio.local / admin123 (email verified)
• user@folio.local / user123 (email verified)

To stop containers:

yarn docker:down

2) Configure environment

• API: copy apps/api/.env.example to .env (repo root) and adjust as needed.
• Web: copy apps/web/.env.example to apps/web/.env.
• Mobile: update API URL in apps/mobile/app.json (see apps/mobile/README.md).

3) Run apps

yarn dev:api
yarn dev:web
yarn dev:mobile

Mobile help:

• Troubleshooting guide: docs/mobile/troubleshoot/README.md

URLs:

• Web: http://localhost:4200
• API: http://localhost:3000
• Swagger UI: http://localhost:3000/api-docs
• Swagger JSON: http://localhost:3000/api-docs.json

Validate

From the repo root:

yarn lint
yarn test
yarn build
yarn format

Credit-based borrowing (Library mode)

Loan workflows now use a credit model:

• New users start with 0 credit balance.
• Borrowing/request eligibility requires a minimum balance (minimum_credit_balance, default 50.00).
• Currency is configurable (credit_currency, default USD).
• Book price and shelf location are configured per book in admin create/edit forms.
• Credit is deducted when a loan request is created, refunded on normal return, and retained for lost loans.

Admin controls are available in Admin → Settings → Loans:

• Borrowing policy (enabled, max concurrent, default duration)
• Credit policy (minimum balance and currency)
• Manual cash payment toggle (enabled by default)
• Stripe/PayPal configuration placeholders with sandbox/production mode fields

Manual top-up is performed in Admin → Users → Edit User by updating Credit Balance. If credit is increased, Folio sends a credit notification email to the user.

Admin external imports

Books

Admins can import book metadata from external providers in the admin panel. This is available at /admin/books/create in the web app and uses admin-only API endpoints.

Providers supported:

• Open Library
• Google Books
• Library of Congress
• Wikidata
• ISBNdb (paid)
• WorldCat (paid)

Required API env vars (see apps/api/.env.example):

• GOOGLE_BOOKS_API_KEY
• ISBNDB_API_KEY (optional ISBNDB_BASE_URL)
• WORLDCAT_WSKEY (requires WORLDCAT_BASE_URL)
• OPENLIBRARY_DEBUG (optional; logs raw OL responses)

ISBN handling:

• The API stores isbn, isbn10, and isbn13 and enforces uniqueness across all three.
• The primary isbn prefers ISBN-13, then ISBN-10, then a provided fallback.

Authors

Admins can search and import author data from external providers when creating or editing authors.

Available in the web UI:

• /admin/authors/create - Create new authors with external data search
• /admin/authors/edit/{id} - "Enrich from External Sources" button

Providers supported:

• Open Library - Author biographies, birth dates, photos, alternate names
• Wikidata - Detailed biographical data via SPARQL queries
• Google Books - Author info with work counts and top works

Features:

• Historical dates: Supports formats like 6th cent. B.C., c. 1564
• Alternate names: Stores multiple name variations (孙武 → Sun Tzu)
• English name priority: Auto-selects Latin-script names when available
• Duplicate detection: Fuzzy matching with 70% similarity threshold
• Field-level enrichment: Select which fields to update from external data
• Deletion protection: Authors with books cannot be deleted

SEO Features

The web application includes comprehensive SEO optimization:

• Meta tags: Dynamic title, description, and keywords for all pages
• Open Graph & Twitter Cards: Rich social media previews for books and authors
• Structured Data (JSON-LD): Schema.org markup for books, authors, and organization
• Canonical URLs: Proper canonicalization to prevent duplicate content
• Robots.txt: Crawler directives with sitemap reference
• Sitemap.xml: Auto-generated sitemap with all public content
• Noindex for private pages: Auth/admin routes are properly excluded

SEO Configuration

Configure SEO settings in the admin panel under Settings:

• Site base URL (for canonical links)
• Default OG image
• Robots policy
• Site name, description, and keywords

Build Process

SEO assets are generated during the web packaging process:

yarn package:web --api-url https://your-api.com

This generates robots.txt and sitemap.xml in the web build output.

Nx basics

To run tasks with Nx:

yarn nx <target> <project-name>

Example:

yarn nx serve web