# LuckyChit Backend API

Backend API for LuckyChit - Digital Chit Fund Management Platform

## Features

- **Authentication & Authorization**: JWT-based authentication with role-based access control
- **User Management**: Create and manage users (managers and members)
- **Database**: PostgreSQL with Sequelize ORM
- **Security**: Helmet, CORS, Rate limiting, Input validation
- **Logging**: Morgan for HTTP logging

## Tech Stack

- **Runtime**: Node.js
- **Framework**: Express.js
- **Database**: PostgreSQL
- **ORM**: Sequelize
- **Authentication**: JWT (jsonwebtoken)
- **Security**: bcrypt, helmet, cors
- **Validation**: Built-in Sequelize validation

## Prerequisites

- Node.js (v16 or higher)
- PostgreSQL (v12 or higher)
- npm or yarn

## Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd backend
   ```

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

3. **Environment Setup**
   ```bash
   cp env.example .env
   ```
   
   Edit `.env` file with your configuration:
   ```env
   NODE_ENV=development
   PORT=3000
   
   # Database Configuration
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=luckychit
   DB_USER=postgres
   DB_PASSWORD=your_password
   
   # JWT Configuration
   JWT_SECRET=your-super-secret-jwt-key
   JWT_EXPIRES_IN=24h
   
   # CORS Configuration
   ALLOWED_ORIGINS=http://localhost:8080
   ```

4. **Database Setup**
   ```sql
   -- Create database
   CREATE DATABASE luckychit;
   
   -- Create user (if needed)
   CREATE USER postgres WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE luckychit TO postgres;
   ```

5. **Run the application**
   ```bash
   # Development mode
   npm run dev
   
   # Production mode
   npm start
   ```

## API Endpoints

### Authentication

#### POST `/api/auth/login`
Login with mobile number and password.

**Request Body:**
```json
{
  "mobile_number": "9999999999",
  "password": "password123"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": "uuid",
      "mobile_number": "9999999999",
      "full_name": "Test User",
      "role": "manager",
      "is_active": true
    }
  }
}
```

#### POST `/api/auth/create-member` (Manager only)
Create a new member account.

**Headers:**
```
Authorization: Bearer <jwt_token>
```

**Request Body:**
```json
{
  "mobile_number": "8888888888",
  "full_name": "John Doe"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Member created successfully",
  "data": {
    "user": {
      "id": "uuid",
      "mobile_number": "8888888888",
      "full_name": "John Doe",
      "role": "member"
    },
    "tempPassword": "abc12345"
  }
}
```

#### GET `/api/auth/profile`
Get current user profile.

**Headers:**
```
Authorization: Bearer <jwt_token>
```

#### PUT `/api/auth/profile`
Update user profile.

**Headers:**
```
Authorization: Bearer <jwt_token>
```

**Request Body:**
```json
{
  "full_name": "Updated Name"
}
```

#### PUT `/api/auth/change-password`
Change user password.

**Headers:**
```
Authorization: Bearer <jwt_token>
```

**Request Body:**
```json
{
  "current_password": "old_password",
  "new_password": "new_password"
}
```

### Health Check

#### GET `/health`
Check API health status.

**Response:**
```json
{
  "success": true,
  "message": "LuckyChit API is running",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "environment": "development"
}
```

## Database Models

### User
- `id` (UUID, Primary Key)
- `mobile_number` (String, Unique)
- `full_name` (String)
- `password_hash` (String)
- `role` (Enum: 'manager', 'member')
- `created_by` (UUID, Foreign Key to User)
- `is_active` (Boolean)
- `last_login` (Date)

### ChitGroup
- `id` (UUID, Primary Key)
- `name` (String)
- `total_value` (Decimal)
- `monthly_installment` (Decimal)
- `duration_months` (Integer)
- `max_members` (Integer)
- `foreman_commission_percentage` (Decimal)
- `draw_date` (Integer)
- `status` (Enum: 'forming', 'active', 'completed')
- `manager_id` (UUID, Foreign Key to User)

### GroupMember
- `id` (UUID, Primary Key)
- `group_id` (UUID, Foreign Key to ChitGroup)
- `user_id` (UUID, Foreign Key to User)
- `joined_date` (Date)
- `status` (Enum: 'active', 'inactive', 'removed')
- `total_paid` (Decimal)
- `total_won` (Decimal)

### Payment
- `id` (UUID, Primary Key)
- `group_id` (UUID, Foreign Key to ChitGroup)
- `user_id` (UUID, Foreign Key to User)
- `month` (Integer)
- `year` (Integer)
- `amount` (Decimal)
- `payment_method` (Enum: 'upi', 'bank_transfer', 'cash', 'cheque')
- `transaction_id` (String)
- `status` (Enum: 'pending', 'success', 'failed', 'cancelled')
- `paid_at` (Date)

### MonthlyDraw
- `id` (UUID, Primary Key)
- `group_id` (UUID, Foreign Key to ChitGroup)
- `month` (Integer)
- `year` (Integer)
- `draw_date` (Date)
- `eligible_members` (JSONB)
- `winner_id` (UUID, Foreign Key to User)
- `prize_amount` (Decimal)
- `server_seed` (String)
- `server_seed_hash` (String)
- `client_seed` (String)
- `nonce` (BigInt)
- `result_hash` (String)
- `status` (Enum: 'pending', 'completed', 'cancelled')

## Development

### Scripts

```bash
# Start development server with nodemon
npm run dev

# Start production server
npm start

# Run tests
npm test
```

### Project Structure

```
src/
├── config/
│   └── database.js          # Database configuration
├── controllers/
│   └── authController.js    # Authentication controller
├── middleware/
│   └── auth.js             # Authentication middleware
├── models/
│   ├── User.js             # User model
│   ├── ChitGroup.js        # ChitGroup model
│   ├── GroupMember.js      # GroupMember model
│   ├── Payment.js          # Payment model
│   ├── MonthlyDraw.js      # MonthlyDraw model
│   └── index.js            # Model associations
├── routes/
│   └── auth.js             # Authentication routes
└── server.js               # Main server file
```

## Security Features

- **JWT Authentication**: Secure token-based authentication
- **Password Hashing**: bcrypt for password security
- **CORS Protection**: Configurable CORS settings
- **Rate Limiting**: Prevent abuse with request limiting
- **Helmet**: Security headers
- **Input Validation**: Sequelize model validation
- **SQL Injection Protection**: Sequelize ORM protection

## Error Handling

The API uses a centralized error handling system:

- **400**: Bad Request (validation errors)
- **401**: Unauthorized (authentication required)
- **403**: Forbidden (insufficient permissions)
- **404**: Not Found (resource not found)
- **429**: Too Many Requests (rate limit exceeded)
- **500**: Internal Server Error (server errors)

## Contributing

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

## License

This project is licensed under the ISC License.
