Library API

Library API is a fullstack library management app built with Next.js, Tailwind CSS, and MongoDB. It includes a public landing page, a protected workspace, internal API routes, bilingual UI, persistent theme preferences, and Swagger-based API documentation.

Features

• Public landing page plus authenticated workspace
• Internal API routes for auth, authors, books, loans, seed data, and OpenAPI
• English and Spanish interface with saved language preference
• Light and dark themes with persistent user preference
• Cookie-based authentication with protected workspace routes
• Swagger UI docs at /api-docs
• Health endpoint at /api/health for Railway readiness checks
• Sample data loader for demo sessions

Tech stack

• Next.js 15
• React 19
• Tailwind CSS
• MongoDB
• Mongoose
• Zod
• JOSE
• Swagger UI
• Docker

Project structure

src/
├── app/
│   ├── (marketing)/        # Public landing page
│   ├── (workspace)/        # Authenticated workspace
│   ├── api/                # Internal API route handlers
│   └── api-docs/           # Swagger UI page
├── components/             # Layout, auth, docs, UI, and feature sections
└── lib/
    ├── auth/               # Session and request auth helpers
    ├── client/             # Client-side API utilities
    ├── constants/          # Shared app constants
    ├── db/                 # Database models, serializers, and connection
    ├── i18n/               # Dictionaries and preference helpers
    ├── services/           # Business logic
    └── validation/         # Zod schemas

Environment variables

Create a local environment file:

cp .env.example .env.local

MONGODB_URI=mongodb://admin:123456@localhost:27017/library-db?authSource=admin
JWT_SECRET=change-this-super-secret-key
NEXT_PUBLIC_APP_NAME=Library API

For Railway, keep the same variable names in your app service:

• MONGODB_URI
• JWT_SECRET
• NEXT_PUBLIC_APP_NAME

Local development

npm install
npm run dev

The app will be available at http://localhost:3000.

Docker

docker-compose up --build

Services:

• library-app at http://localhost:3000
• library-mongodb at mongodb://localhost:27017

Railway deployment

This repository is configured for Railway with:

• next.config.ts using output: "standalone"
• A production Dockerfile for Railway builds
• railway.json for config-as-code
• /api/health as the deployment healthcheck

Recommended setup

1. Push this repository to GitHub.
2. In Railway, create a new project and choose Deploy from GitHub repo.
3. Add a MongoDB service to the same Railway project.
4. In the app service, add these variables:
   • MONGODB_URI as a reference variable pointing to your MongoDB connection string
   • JWT_SECRET as a strong secret value
   • NEXT_PUBLIC_APP_NAME=Library API
5. Open the app service Settings -> Networking and generate a public domain.
6. Redeploy the app service after adding variables if Railway does not redeploy automatically.

Notes

• Railway automatically injects PORT, and the container is configured to listen on it.
• The deployment will only become active when /api/health returns HTTP 200.
• If the app is missing MONGODB_URI or JWT_SECRET, the healthcheck returns 503 and Railway will keep the deployment from going live.
• Railway supports defining settings in code via railway.json, and those values override dashboard deploy settings for the current deployment.

Main routes

• / public landing page
• /login authentication screen
• /dashboard workspace overview
• /authors author management
• /books catalog management
• /loans lending management
• /api/health deployment health endpoint
• /api-docs Swagger UI documentation

Scripts

npm run dev
npm run lint
npm run build
npm run start

Contributor notes

• Use npm, not pnpm, for dependency management in this repository.
• Keep OpenAPI docs in sync with backend route changes.
• Keep both locales updated when changing user-facing copy.
• Keep Railway deployment settings in sync with railway.json and /api/health.

Verification

Before shipping changes, run:

npm run lint
npm run build