Mega Book Store

A full-stack bookstore platform with authentication, admin document ingestion, and a Retrieval-Augmented Generation (RAG) assistant for contextual Q&A.

Overview

Mega Book Store combines a modern React frontend with an Express + MongoDB backend and a RAG-powered chat flow. Admin users can upload PDF/DOCX content to build a searchable knowledge base, and authenticated users can ask questions that are answered from retrieved context.

Features

Authentication with role-based authorization (admin, user)
Book catalog browsing and pricing display in ETB
Admin knowledge-base ingestion pipeline (PDF/DOCX)
Text extraction, chunking, embedding, and vector retrieval
RAG chat API with SSE streaming support
Graceful maintenance response when provider quota/rate limits are hit

Tech Stack

Frontend

React 19
TypeScript
Vite 6
Tailwind CSS
Zustand
React Router

Backend

Node.js (ESM)
Express 5
MongoDB + Mongoose
JWT authentication
OAuth 2.0 (Google)
Multer for uploads

AI / RAG

Gemini (@google/genai) for answer generation
Voyage AI or Gemini embeddings (configurable)
MongoDB vector search over chunk embeddings

Architecture

Admin uploads documents via /api/admin/documents.
Server extracts and cleans text.
Text is chunked and embedded.
Chunks are stored in rag_chunks with metadata.
Chat query is embedded and matched using vector search.
Retrieved context is passed to Gemini for final response.

Getting Started

Clone the repository.
Install dependencies for both apps.
Configure environment variables.
Start server and client.

Configuration

Create these files:

client/.env
server/.env

You can start from the included templates:

cp client/.env.example client/.env
cp server/.env.example server/.env

Example values:

# client/.env
VITE_API_BASE_URL=

# server/.env
PORT=4000
CLIENT_ORIGIN=http://localhost:5173
MONGODB_URI=<your-mongodb-uri>
JWT_SECRET=<your-jwt-secret>
GEMINI_API_KEY=<your-gemini-api-key>
VOYAGE_API_KEY=<your-voyage-api-key>
EMBEDDING_PROVIDER=voyage

Running the Apps

# terminal 1
cd server
npm run dev

# terminal 2
cd client
npm run dev

Frontend: http://localhost:5173

Docker Workflow

Quick Start (Copy/Paste)

Run this from the project root to start everything in development mode:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

To stop it:

docker compose -f docker-compose.yml -f docker-compose.dev.yml down

This repository includes Docker support for both development and production:

docker-compose.yml (shared/base config)
docker-compose.dev.yml (hot-reload development stack)
docker-compose.prod.yml (optimized production stack)

Docker Prerequisites

Docker Engine + Docker Compose plugin installed.
External MongoDB connection string configured in server/.env (MONGODB_URI).

Start Development Stack (hot reload)

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Frontend: http://localhost:5173
Backend: http://localhost:4000

The dev stack uses Vite proxying (/api, /uploads) to the server container.

Start Production Stack

docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build -d

Frontend (Nginx): http://localhost
Backend (direct): http://localhost:4000

Nginx serves the frontend and reverse-proxies /api and /uploads to the backend service.

Stop Any Stack

docker compose -f docker-compose.yml -f docker-compose.dev.yml down
docker compose -f docker-compose.yml -f docker-compose.prod.yml down

Run Seed Commands in Docker

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm server npm run seed:books
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm server npm run seed:users

API Endpoints

Auth

POST /api/auth/signup
POST /api/auth/login
POST /api/auth/google
GET /api/auth/me

Books

GET /api/books

Admin

POST /api/admin/documents
GET /api/admin/documents
DELETE /api/admin/documents/:id

Chat

POST /api/chat
GET /api/chat/stream
GET /api/chat/sessions
GET /api/chat/sessions/:id

Usage Examples

Upload a knowledge document (admin)

Use multipart form data with field name file to upload PDF or DOCX content.

Ask a chat question (authenticated user)

Send POST /api/chat

Frontend: http://localhost:5173
Backend: http://localhost:4000

Production Stack

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

Frontend (Nginx): http://localhost
Backend: http://localhost:4000

Stopping

docker compose -f docker-compose.yml -f docker-compose.dev.yml down
docker compose -f docker-compose.yml -f docker-compose.prod.yml down

Seeding Data (in Docker)

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm server npm run seed:books
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm server npm run seed:users

Networking, Ports, Security

Default ports: 5173 (frontend), 4000 (backend)
Nginx reverse proxies /api and /uploads in production
Ensure secrets are never committed; use .env files only
MongoDB must be accessible from Docker containers

3. Demo / Screenshots

4. Tech Stack

Frontend:

React 19, TypeScript, Vite 6, Tailwind CSS, Zustand, React Router

Backend:

Node.js (ESM), Express 5, MongoDB + Mongoose, JWT, OAuth 2.0 (Google), Multer

AI / RAG:

Gemini (@google/genai), Voyage AI (embeddings), MongoDB Atlas Vector Search

DevOps:

Docker, Docker Compose, Nginx (prod)

5. Architecture Overview

flowchart TD
    A[Admin Uploads Document] --> B[Text Extraction & Cleaning]
    B --> C[Chunking & Embedding]
    C --> D[Store Chunks in MongoDB]
    E[User Sends Chat Query] --> F[Embed Query]
    F --> G[Vector Search]
    G --> H[Retrieve Top Chunks]
    H --> I[Gemini LLM Generates Answer]
    I --> J[Stream Response to User]

Auth Flow:

JWT for session, Google OAuth for SSO
Role-based access for admin endpoints

Frontend/Backend Interaction:

REST API for CRUD, SSE for chat streaming
Vite dev proxy in development, Nginx in production

6. Feature Breakdown

Authentication

JWT login/signup, Google OAuth
/api/auth/signup, /api/auth/login, /api/auth/google, /api/auth/me

Book Catalog

/api/books (search, filter, pagination)

Admin Knowledge Base

/api/admin/documents (upload/list/delete)
PDF/DOCX ingestion, chunking, embedding

Chat & RAG

/api/chat (Q&A), /api/chat/stream (SSE)
/api/chat/sessions, /api/chat/sessions/:id
Contextual retrieval, Gemini answer generation

Real-Time & Streaming

SSE for chat responses

7. Folder Structure

oak-&-ink-bookstore/
  client/    # React frontend
    components/
    pages/
    services/
    store/
    ...
  server/    # Express API + RAG
    config/
    middleware/
    models/
    routes/
    scripts/
    services/
    uploads/
    ...
  docker-compose.yml
  docker-compose.dev.yml
  docker-compose.prod.yml
  README.md
  LICENSE

8. Environment Variables

`client/.env.example`

# Set to empty to use Vite/Nginx proxy routes (/api, /uploads)
VITE_API_BASE_URL=
# Optional, used by Vite dev proxy inside Docker dev stack
VITE_DEV_PROXY_TARGET=http://server:4000
# Optional direct key injection used by existing app config
GEMINI_API_KEY=

`server/.env.example`

PORT=4000
CLIENT_ORIGIN=http://localhost:5173,http://localhost
MONGODB_URI=<your-mongodb-uri>
MONGODB_DB_NAME=mega_book_store_chat
JWT_SECRET=<your-jwt-secret>
GEMINI_API_KEY=<your-gemini-api-key>
VOYAGE_API_KEY=<your-voyage-api-key>
EMBEDDING_PROVIDER=voyage
VECTOR_INDEX_NAME=chunk_vector_index
EMBEDDING_DIMENSIONS=1024
GOOGLE_CLIENT_ID=<your-google-client-id>
LOG_MEMORY=false
SEED_ADMIN_EMAIL=admin@megabookstore.com
SEED_ADMIN_PASSWORD=Admin@12345

9. Manual Installation

# 1. Clone the repository
git clone <repo-url>
cd oak-&-ink-bookstore

# 2. Install dependencies
cd server && npm install && cd ../client && npm install

# 3. Configure environment variables
cp ../server/.env.example ../server/.env
cp ../client/.env.example ../client/.env
# Edit .env files as needed

# 4. Start development servers
cd ../server && npm run dev
# In another terminal:
cd ../client && npm run dev

10. API Endpoints & Events

Auth

POST /api/auth/signup — Register new user
POST /api/auth/login — Login with email/password
POST /api/auth/google — Google OAuth
GET /api/auth/me — Get current user

Books

GET /api/books — List/search books

Admin

POST /api/admin/documents — Upload document (admin)
GET /api/admin/documents — List documents
DELETE /api/admin/documents/:id — Delete document

Chat

POST /api/chat — Ask question (RAG)
GET /api/chat/stream — SSE chat stream
GET /api/chat/sessions — List chat sessions
GET /api/chat/sessions/:id — Get session details

Events

REST: Standard JSON request/response
SSE: Server-Sent Events for streaming chat answers

11. Future Improvements

User profile management
Book purchasing & order history
Admin analytics dashboard
Multi-language support
Enhanced document ingestion (more formats)
Rate limiting & abuse prevention
CI/CD pipeline & test coverage

12. License & Contact

License: MIT — see LICENSE

Author: Fuad Sano Contact: [conatacts.fuad@gmail.com]

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
client		client
server		server
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json

Folders and files

Latest commit

History

Repository files navigation

Mega Book Store

Table of Contents

Overview

Features

Tech Stack

Frontend

Backend

AI / RAG

Architecture

Getting Started

Configuration

Running the Apps

Docker Workflow

Quick Start (Copy/Paste)

Docker Prerequisites

Start Development Stack (hot reload)

Start Production Stack

Stop Any Stack

Run Seed Commands in Docker

API Endpoints

Auth

Books

Admin

Chat

Usage Examples

Upload a knowledge document (admin)

Ask a chat question (authenticated user)

Production Stack

Stopping

Seeding Data (in Docker)

Networking, Ports, Security

3. Demo / Screenshots

4. Tech Stack

5. Architecture Overview

6. Feature Breakdown

Authentication

Book Catalog

Admin Knowledge Base

Chat & RAG

Real-Time & Streaming

7. Folder Structure

8. Environment Variables

client/.env.example

server/.env.example

9. Manual Installation

10. API Endpoints & Events

Auth

Books

Admin

Chat

Events

11. Future Improvements

12. License & Contact

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`client/.env.example`

`server/.env.example`

Packages