📚 OmniShelf

A personal media library management application that helps you organize and track your books, movies, comics, and music in one place. Features AI-powered assistant, smart collections, and comprehensive analytics.

✨ Key Features

• Multi-Media Library Management: Track and organize books, movies, comics, and music with detailed metadata, tags, and custom cover images
• Smart Collections: Create custom collections to group your media items by themes, favorites, or any criteria you choose
• AI-Powered Assistant: Chat with an intelligent agent that can search the web, add media to your library, and provide recommendations using Google Gemini + Tavily
• Analytics Dashboard: Gain insights into your media consumption with visual statistics and breakdowns by type and status
• User Authentication: Secure registration and login with JWT-based authentication and email verification

🛠️ Tech Stack

Backend

• NestJS - Node.js framework with TypeScript
• PostgreSQL - Primary database
• TypeORM - Database ORM with migrations
• LangChain + Google Gemini - AI agent orchestration
• Tavily - Web search integration
• Passport.js - JWT authentication
• Swagger - API documentation

Frontend

• Next.js 16 - React framework with App Router
• React 19 - UI library
• TailwindCSS 4 - Styling
• Radix UI + shadcn/ui - UI components
• TanStack Query - Data fetching and caching
• React Hook Form + Zod - Form validation

🚀 Installation

Prerequisites

• Node.js 18+
• Docker & Docker Compose
• pnpm (recommended) or npm

1. Clone and Setup

git clone https://github.com/YuITC/OmniShelf.git
cd OmniShelf

2. Start Database

docker-compose up -d

3. Backend Setup

cd backend
cp .env.example .env  # Configure your environment variables
npm install
npm run migration:run
npm run start:dev

4. Frontend Setup

cd frontend
cp .env.example .env.local  # Configure API URL (optional)
npm install
npm run dev

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000/api
• Swagger Docs: http://localhost:4000/api/docs
• Adminer (DB): http://localhost:8080

📖 Usage

Managing Media

1. Add Media: Click "Add Media" on the dashboard, fill in details (title, type, author, tags), and save
2. Track Progress: Update status (Planning, Watching, Completed, Dropped) for each media item
3. Organize: Use tags and filters to quickly find media in your library

Using Collections

1. Navigate to Collections page
2. Create a new collection with a name and optional color
3. Add media items to collections from the dashboard

AI Assistant

1. Go to AI Chat page
2. Ask questions like:
   • "Search for popular sci-fi movies from 2024"
   • "Add One Piece to my library as a comic"
   • "What's in my library?"
   • "Create a collection called Favorites"

📁 Project Structure

OmniShelf/
├── backend/                            # NestJS API server
│   └── src/
│       ├── modules/
│       │   ├── ai/                     # AI agent with tools
│       │   ├── analytics/              # Statistics aggregation
│       │   ├── auth/                   # JWT authentication
│       │   ├── collection/             # Media collections
│       │   ├── email/                  # Email services
│       │   ├── email-verification/     # Email verification services
│       │   ├── health/                 # Health checks
│       │   ├── media/                  # Core media CRUD
│       │   └── user/                   # User management
│       └── database/                   # TypeORM migrations
├── frontend/                           # Next.js application
│   └── src/
│       ├── app/                        # App Router pages
│       ├── components/                 # Shared UI components
│       ├── context/                    # React contexts
│       ├── features/                   # Feature modules
│       └── lib/                        # Utility libraries
└── docker-compose.yml                  # PostgreSQL + Adminer

📫 Contact

If you find this project useful, consider ⭐️ starring the repository or contributing to further improvements!

For any questions, feature requests, or collaboration opportunities, feel free to reach out: tainguyenphu2502@gmail.com