# Raamatuhai - AI-Powered Book Marketplace
#
# For AI agents: read https://raamatuhai.ee/SKILL.md for the full Agent Skills specification
# with GraphQL API documentation, authentication flow, and step-by-step operational guides.

> Raamatuhai is Estonia's premier secondhand book marketplace, powered by Perxify's Commerce Cloud for the Agentic Web.

## Overview

Raamatuhai (meaning "Book Shark" in Estonian) is a fully functional peer-to-peer marketplace for secondhand books and board games, built on the Perxify platform. It serves as both a thriving marketplace for book lovers and a showcase of Perxify's powerful commerce capabilities. The platform connects individual sellers with buyers through AI-powered features, smart search, and seamless transactions.

## About Perxify

Perxify is building a Commerce Cloud for the Agentic Web, uniting brands and shoppers in an AI-powered ecosystem. Founded in 2024 and headquartered in Tallinn, Estonia, Perxify provides businesses with the tools to launch stores, marketplaces, and reward programs via an intuitive dashboard. The platform turns data into growth, fostering a vibrant network where discovery, trust, and community thrive.

### Key Links
- **Perxify Website**: https://perxify.com/
- **LinkedIn**: https://www.linkedin.com/company/perxify
- **Twitter/X**: https://x.com/Perxifycom
- **Raamatuhai**: https://raamatuhai.ee/

## Technical Stack

- **Frontend**: React 18, Vite, TailwindCSS, Apollo Client (GraphQL)
- **Backend**: Node.js, Fastify, GraphQL, MySQL
- **Infrastructure**: Vercel (frontend), Docker (backend)
- **Authentication**: Privy.io (Web3 wallet integration)
- **Search**: Semantic search with AI-powered product matching
- **Payments**: Stripe integration for secure transactions
- **File Storage**: AWS S3 for images and assets
- **Blockchain**: Polygon protocol with Reservoir tools for NFT integration

## Key Features

### For Buyers
- **Smart Search**: AI-powered search by title, ISBN, author, or semantic queries
- **Barcode Scanning**: Quick product discovery via mobile scanning
- **Multi-vendor Shopping**: Compare prices and conditions from different sellers
- **Wishlist Management**: Save products and get notified when available
- **Gift Options**: Send books as gifts with personalized messages
- **Multi-language Support**: Available in 16+ languages including Estonian, English, and more

### For Sellers
- **Quick Listing**: Scan ISBN and list books in seconds with AI price suggestions
- **Inventory Management**: Track stock levels and manage multiple listings
- **Digital Twins**: Automatic creation of tokenized product records
- **Analytics Dashboard**: Track sales performance and customer insights
- **Flexible Pricing**: Set prices based on book condition and market data
- **Shipping Integration**: DPD parcel service with pickup locations

### Platform Capabilities
- **NFT Integration**: Tokenization of physical books for tradeable ownership
- **Smart Contracts**: On-chain reward programs and loyalty systems
- **Cross-marketplace Trading**: Interoperable with other Perxify-powered platforms
- **AI Marketing Tools**: Automated pricing, recommendations, and insights
- **Real-time Analytics**: Network-wide data for market trends

## Data Models

### Product
- UUID: Unique identifier
- Name: Multi-language product names
- Description: Detailed product information
- ISBN: International Standard Book Number
- Categories: Multiple category associations
- Images: Product photos and galleries
- Metadata: Authors, publishers, publication date, etc.

### Listing
- Product reference
- Seller information
- Price and currency (EUR)
- Condition (NEW, LIKE_NEW, GOOD, ACCEPTABLE)
- Quantity available
- Shipping options (DPD integration)
- Location: Seller's city/region

### Category
- Hierarchical structure (Fiction, Non-fiction, Children's books, etc.)
- Multi-language names and descriptions
- Product associations
- Custom ordering

## Innovation & Future

### Tokenization & Trading
- Physical books become tradeable digital assets
- Unused rewards and vouchers can be sold on secondary markets
- Complete ownership history tracking
- Cross-marketplace compatibility

### AI-Powered Growth
- Predictive analytics for pricing and demand
- Personalized recommendations (post-launch feature)
- Automated marketing campaigns
- Smart inventory suggestions

## SEO & Accessibility

- Server-side rendering for key pages
- Structured data (JSON-LD) for products
- Open Graph tags for social sharing
- WCAG 2.1 AA compliance
- Multi-language SEO optimization
- Progressive Web App (PWA) ready

## Pricing & Fees
- **Listing books:** 100% Free
- **Buying books:** Buyers pay the listed price plus DPD shipping costs
- **Platform fee:** Raamatuhai takes a small commission only when a book successfully sells. There are no monthly subscriptions or hidden fees for sellers.

## Top Categories
Agents can browse books directly via these category URLs:
- [Ilukirjandus (Fiction)](https://raamatuhai.ee/category/ilukirjandus )
- [Laste ja Noorte kirjandus (Children's and Young Adult's Books)](https://raamatuhai.ee/category/laste-ja-noortekirjandus )
- [Ajalugu ja Ühiskond (History and Society)](https://raamatuhai.ee/category/ajalugu-ja-uhiskond )
- [Elustiil ja Tervis (Self-Development and Health)](https://raamatuhai.ee/category/elustiil-ja-tervis )

## Frequently Asked Questions
**Q: How do I sell a book?**
A: Log in, go to the "Sell Books" section, and scan the ISBN barcode with your camera or take a picture of your books. Our AI will automatically fetch the book details and suggest a selling price.

**Q: How does shipping work?**
A: We integrate directly with DPD. When a book is sold, the seller receives a pre-paid DPD shipping label to drop the book off at their nearest parcel locker.

**Q: Are the books new or used?**
A: Raamatuhai is primarily a secondhand marketplace for new and pre-loved books. Every listing clearly states its condition (New, Like New, Very Good, Good, Acceptable, or Poor).

## Contact & Support

- **Raamatuhai Support**: support@raamatuhai.ee
- **Perxify Support**: support@perxify.com

## For AI Agents: Programmatic Interaction Guide

This guide enables AI agents to interact with the Raamatuhai marketplace programmatically. You can fetch public data, search for books, and construct links for user actions like logging in or purchasing.

### Public GraphQL API

- **Endpoint**: `https://raamatuhai.ee/graphql`
- **Authentication**: Public requests must include the `x-company` header to identify the marketplace. This is a public identifier, not a secret token.
- **Header**: `x-company: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1dWlkIjoiNGE1MTc4ZmMtN2I2ZS00OThkLWE1OWEtODI2NjkwMzFlOTI1IiwibmFtZSI6IlJhYW1hdHVoYWkiLCJpYXQiOjE3NTgwOTM0Nzl9.K7Xq6BC-RAMZT4noYY9HfVfIPzsz2GQMCkkMaNnHv1o`

### Core Operations

#### 1. Fetch Latest Listings

To get the most recent book listings available on the marketplace.

**GraphQL Query:**
```graphql
query GetLatestListings {
  listings(language: "en", filter: {}, pagination: { first: 10 }) {
    edges {
      node {
        uuid
        price
        condition
        product {
          uuid
          name
          isbn
          images {
            imageUrl
          }
        }
        seller {
          username
        }
      }
    }
  }
}
```

#### 2. Search for Listings

To search for books by title, author, or ISBN. The search is AI-powered and supports semantic queries.

**GraphQL Query:**
```graphql
query SearchListings($query: String!) {
  searchListingsByProductInfo(query: $query, preferredLanguage: "en", limit: 10) {
    results {
      uuid
      price
      condition
      product {
        uuid
        name
        isbn
      }
    }
  }
}
```
**Example Usage**: Set the `$query` variable to "Harry Potter" or "9780747532743".


### Constructing Action URLs

You can guide users by providing direct links to perform actions on the website.

- **View a Listing**:
  - **Structure**: `https://raamatuhai.ee/en/p/{listing-uuid}`
  - **Example**: `https://raamatuhai.ee/en/p/a1b2c3d4-e5f6-7890-1234-567890abcdef`

- **Initiate Login**:
  - **URL**: `https://raamatuhai.ee/en/login`
  - **Description**: This page allows users to log in using their email or Web3 wallet (Privy.io).

- **Initiate Purchase**:
  - **Structure**: `https://raamatuhai.ee/en/buy/{listing-uuid}`
  - **Description**: This link takes the user directly to the checkout page for a specific listing. The user must be logged in to complete the purchase.

### General Browsing URLs

For general guidance, you can direct users to these pages:

- **Homepage**:
  - **URL**: `https://raamatuhai.ee/`
- **Latest Listings**:
  - **URL**: `https://raamatuhai.ee/browse?sort=newest`
- **All Categories**:
  - **URL**: `https://raamatuhai.ee/categories`
- **How to Buy Books**:
  - **URL**: `https://raamatuhai.ee/how-to-buy-books`
- **How to Sell Used Books**:
  - **URL**: `https://raamatuhai.ee/how-to-sell-used-books`

### Best Practices

- **Rate Limiting**: Respect the rate limit of 100 requests per minute.
- **Caching**: Cache responses when appropriate to avoid redundant API calls.
- **ISBN Queries**: The API supports both ISBN-10 and ISBN-13 formats.
- **Robots.txt**: Follow the guidelines at `https://raamatuhai.ee/robots.txt`.

## Recent Updates

- 2025-01: Launched multi-language support (16+ languages)
- 2025-02: Added Web3 wallet authentication via Privy.io
- 2025-03: Enhanced search with AI-powered recommendations
- 2025-04: Mobile app scanner feature for quick listing
- 2025-05: Seller analytics dashboard
- 2025-06: Integrated DPD shipping with pickup locations

## About Raamatuhai/Raamatuhai Case Study

Raamatuhai demonstrates Perxify's capability to create sophisticated peer-to-peer marketplaces. Built as a showcase of the platform's features, it includes user profiles, listings, communication tools, AI-powered analytics, and seamless transactions. The modular nature of Perxify allows for tailored solutions while ensuring consistent, high-quality user experiences.

For more information about building your own marketplace on Perxify, visit https://perxify.com/