# 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
```bash
git clone <repository-url>
cd receipt-verification-api
```

2. Install dependencies
```bash
npm install
```

3. Set up environment variables
```bash
cp .env.example .env
# Edit .env with your configuration
```

4. Set up the database
```bash
npx prisma generate
npx prisma db push
```

5. Start the development server
```bash
npm run start:dev
```

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

## Environment Variables

```env
# 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

```bash
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.