Yaltopia-Tickets-Backend/README.md

Receipt & Ticket Verification API

A production-ready backend API for receipt & ticket verification system with OCR processing, role-based access, reporting, and performance monitoring.

Features

• 🔐 Authentication & Authorization

  • JWT-based authentication
  • Supabase integration for OTP
  • Role-based access control (RBAC)
  • Telegram ID compatibility

• 👥 User Management

  • System Admin, Business Owner, Staff, Auditor roles
  • Hierarchical user creation
  • Redis-cached role lookups

• 🧾 Receipt Processing (Coming Soon)

  • OCR with Tesseract.js
  • Asynchronous processing with BullMQ
  • Duplicate detection
  • Fraud flagging

• 📊 Reporting & Analytics (Coming Soon)

  • Daily sales summaries
  • Transaction reports
  • Performance metrics
  • CSV/PDF exports

Tech Stack

• Framework: NestJS (TypeScript)
• Database: PostgreSQL with Prisma ORM
• Cache: Redis
• Queue: BullMQ
• Auth: JWT + Supabase
• Storage: Supabase Storage
• OCR: Tesseract.js

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL
• Redis
• Supabase account

Installation

1. Clone the repository

git clone <repository-url>
cd receipt-verification-api

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env
# Edit .env with your configuration

4. Set up the database

npx prisma generate
npx prisma db push

5. Start the development server

npm run start:dev

The API will be available at http://localhost:3000/api/v1

Environment Variables

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/receipt_verification?schema=public"

# Supabase
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"

# JWT
JWT_SECRET="your-jwt-secret-key"
JWT_EXPIRES_IN="7d"

# Redis
REDIS_HOST="localhost"
REDIS_PORT=6379
REDIS_PASSWORD=""

# App
PORT=3000
NODE_ENV="development"

API Endpoints

Authentication

• POST /api/v1/auth/login - Login with credentials
• POST /api/v1/auth/register - Register new user (admin/owner only)
• POST /api/v1/auth/request-otp - Request OTP via Supabase
• POST /api/v1/auth/verify-otp - Verify OTP and login
• GET /api/v1/auth/profile - Get current user profile
• GET /api/v1/auth/validate - Validate JWT token

Users

• GET /api/v1/users - List users (filtered by role)
• GET /api/v1/users/:id - Get user by ID
• POST /api/v1/users/staff - Create staff/auditor
• PATCH /api/v1/users/:id - Update user
• DELETE /api/v1/users/:id - Deactivate user
• GET /api/v1/users/my-staff - Get owner's staff

User Roles & Permissions

System Admin

• Full system access
• Manage all users
• View all reports
• System configuration

Business Owner

• Create/manage staff and auditors
• View business reports
• Manage receipts
• Verify transactions

Staff (Cashier)

• Upload receipts
• View own receipts
• Basic verification tasks

Auditor

• Read-only access to reports
• View receipts for auditing
• No modification permissions

Database Schema

The system uses Prisma with PostgreSQL. Key entities:

• User: Authentication and role management
• Receipt: Receipt data and OCR results
• Verification: Receipt verification records
• PerformanceMetric: System performance tracking

Development

Scripts

npm run start:dev      # Development server with hot reload
npm run build          # Build for production
npm run start:prod     # Start production server
npm run lint           # Run ESLint
npm run test           # Run tests
npm run prisma:studio  # Open Prisma Studio

Project Structure

src/
├── features/          # Feature modules
│   ├── auth/         # Authentication & authorization
│   ├── users/        # User management
│   ├── receipts/     # Receipt processing (coming soon)
│   ├── ocr/          # OCR processing (coming soon)
│   └── reports/      # Reporting (coming soon)
├── shared/           # Shared utilities
│   ├── config/       # Configuration
│   ├── constants/    # Constants and enums
│   ├── decorators/   # Custom decorators
│   ├── guards/       # Auth guards
│   ├── services/     # Shared services
│   └── utils/        # Utility functions
└── prisma/           # Database schema

Security Features

• JWT token authentication
• Role-based access control
• Password hashing with bcrypt
• Request validation with class-validator
• CORS protection
• Rate limiting (recommended for production)

Caching Strategy

• User roles cached in Redis (1 hour TTL)
• User profiles cached (5 minutes TTL)
• Automatic cache invalidation on updates

Next Steps

1. Implement OCR module with BullMQ
2. Add receipt upload and processing
3. Create verification workflows
4. Build reporting system
5. Add performance monitoring
6. Implement notification system

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License.