BookStore Microservices

A microservice-based bookstore built with Django REST Framework, Docker Compose, and independent databases.

Architecture

#	Service	Port	Description
1	api-gateway	8000	Routes all client requests to downstream services
2	staff-service	8001	Staff user management (CRUD)
3	manager-service	8002	Manager user management (CRUD)
4	customer-service	8003	Customer registration (auto-creates cart) & login
5	catalog-service	8004	Book categories/catalogs
6	product-service	8005	Product CRUD (books, laptops, fashion), search, stock
7	cart-service	8006	Shopping cart add/view/update/remove
8	order-service	8007	Order creation (triggers payment & shipping)
9	ship-service	8008	Shipment tracking & status
10	pay-service	8009	Payment processing & refunds
11	comment-rate-service	8010	Book ratings & comments
12	recommender-ai-service	8011	AI-based book recommendations (collaborative filtering)

Quick Start

docker-compose up --build

API Endpoints (via Gateway at port 8000)

Customers

• POST /api/customers/register/ — Register (auto-creates cart)
• POST /api/customers/login/
• GET /api/customers/

Books

• GET /api/books/ — List all books
• POST /api/books/ — Create book (staff)
• GET /api/books/{id}/
• GET /api/books/search/?q=keyword
• GET /api/books/by_catalog/?catalog_id=1

Cart

• GET /api/carts/by_customer/?customer_id=1 — View cart
• POST /api/carts/add_item/ — Add book to cart {customer_id, book_id, quantity}
• PUT /api/carts/update_item/ — Update quantity {customer_id, book_id, quantity}
• DELETE /api/carts/remove_item/?customer_id=1&book_id=1

Orders

• POST /api/orders/create_from_cart/ — Create order {customer_id, payment_method, shipping_method, shipping_address}
• GET /api/orders/by_customer/?customer_id=1
• POST /api/orders/{id}/cancel/

Payments

• GET /api/payments/by_order/?order_id=1
• POST /api/payments/{id}/process/
• POST /api/payments/{id}/refund/

Shipping

• GET /api/shipments/by_order/?order_id=1
• GET /api/shipments/track/?tracking_number=SHIP-XXXX
• POST /api/shipments/{id}/update_status/ — {status: "shipped"}

Comments & Ratings

• POST /api/comments/ — {customer_id, book_id, rating, comment}
• GET /api/comments/by_book/?book_id=1
• GET /api/comments/by_customer/?customer_id=1

Recommendations

• GET /api/recommendations/?customer_id=1&top_n=5

Catalogs

• GET /api/catalogs/
• POST /api/catalogs/ — {name, description}

Staff & Managers

• GET /api/staff/
• POST /api/staff/
• GET /api/managers/
• POST /api/managers/

Inter-Service Communication

All communication between services is done via REST HTTP calls using Python requests library:

• customer-service → cart-service: Auto-create cart on registration
• order-service → cart-service: Fetch cart items
• order-service → product-service: Fetch prices, update stock
• order-service → pay-service: Create payment
• order-service → ship-service: Create shipment
• cart-service → product-service: Enrich cart items with product details
• recommender-ai-service → comment-rate-service: Fetch all ratings
• recommender-ai-service → product-service: Fetch product details
• api-gateway → all services: Proxy HTTP requests

Technical Stack

Backend

• Framework: Django 4.x + Django REST Framework
• Language: Python 3.11
• Database: PostgreSQL 15 (independent database per service)
• Inter-service: REST HTTP (requests library)
• Containerization: Docker + Docker Compose
• AI: Collaborative filtering (recommender-ai-service)

Frontend

• Main App (port 3000): React 18 + Vite + TypeScript
• Admin Dashboard (port 3001): Next.js 14 + TypeScript + Shadcn UI
• Styling: Tailwind CSS
• Icons: Lucide React
• Package Manager: Yarn

Frontend Applications

Customer Web App (port 3000)

Main customer-facing application built with React + Vite.

cd frontend
yarn install
yarn dev

Admin Dashboard (port 3001)

Prisma Studio-like data management interface built with Next.js 14 and Shadcn UI.

cd admin-dashboard
yarn install
yarn dev

Access at: http://localhost:3001

Features:

• 📊 View all service data in beautiful tables
• 🔍 Search and filter data
• 📄 Pagination
• 🔄 Real-time refresh
• 📱 Fully responsive

Seed Data

The project includes seed scripts to populate databases with test data:

# PowerShell (Windows)
.\seed_data.ps1

# Batch (Windows)
seed_data.bat

# Bash (Linux/Mac)
./seed_data.sh

This will create:

• 15 Catalogs
• 10 Staff members
• 5 Managers
• 50 Customers
• 100+ Books
• 30 Carts with items
• 100 Orders with items
• 100 Payments
• 100 Shipments
• 200 Comments/Ratings

📚 Documentation

• Quick Start Guide - Fast setup and common commands
• GitHub Copilot Guide - Using Copilot with this project
• Admin Dashboard Guide - Admin dashboard documentation
• Copilot Instructions - AI assistance configuration

🚀 Getting Started

1. Clone the repository

   git clone <repository-url>
   cd bookstore_microservice

2. Start all services

   docker-compose up --build -d

3. Wait for services to be healthy

   docker-compose ps

4. Seed test data

   .\seed_data.ps1

5. Access applications

   • Frontend: http://localhost:3000
   • Admin Dashboard: http://localhost:3001
   • API Gateway: http://localhost:8000

🛠️ Development

Backend Services

# View logs
docker-compose logs -f [service-name]

# Execute commands in container
docker-compose exec [service-name] bash

# Run migrations
docker-compose exec [service-name] python manage.py migrate

# Create superuser
docker-compose exec [service-name] python manage.py createsuperuser

Frontend Development

# React App
cd frontend
yarn install
yarn dev

# Admin Dashboard
cd admin-dashboard
yarn install
yarn dev

📊 Service URLs

Service	Development	Docker	Admin Link
API Gateway	-	:8000	-
Frontend	:3000	:3000	-
Admin Dashboard	:3000	:3001	View
Catalog Service	-	:8004	Data
Book Service	-	:8005	Data
Customer Service	-	:8003	Data
Staff Service	-	:8001	Data
Manager Service	-	:8002	Data
Cart Service	-	:8006	Data
Order Service	-	:8007	Data
Payment Service	-	:8009	Data
Shipping Service	-	:8008	Data
Comment Service	-	:8010	Data

🤝 Contributing

Contributions are welcome! Please read the coding standards in the Copilot Instructions file.

📄 License

This project is for educational purposes.

🔗 Useful Resources

• Django REST Framework
• Next.js 14 Documentation
• Shadcn UI Components
• Tailwind CSS
• Docker Compose
• PostgreSQL

---

Built with ❤️ using Microservices Architecture