tm_back/README.md

# Tender Management System - Dual User Architecture

A comprehensive tender management backend system built with Go, featuring separate authentication and authorization for mobile app customers and panel admin users.

## 🏗️ Architecture Overview

This system implements **Clean Architecture** principles with a dual user system:

### User Types

1. **Customers (Mobile App Users)**
   - End users who interact through mobile applications
   - Can register, view tenders, manage company profiles
   - Role-based access: `customer_user`, `customer_manager`

2. **Panel Users (Admin/Staff)**  
   - Administrative users who manage the system
   - Can manage customers, tenders, companies, and system settings
   - Role-based access: `admin`, `moderator`, `support`, `analyst`

### Layer Structure

```
┌─────────────────────────────────────────────────────────────┐
│                      Handler Layer                          │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐   │
│  │ Customer Auth   │ │ User Auth       │ │ Legacy Auth  │   │
│  │ Handler         │ │ Handler         │ │ Handler      │   │
│  └─────────────────┘ └─────────────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                      Service Layer                          │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐   │
│  │ Customer Auth   │ │ User Auth       │ │ Customer     │   │
│  │ Service         │ │ Service         │ │ Service      │   │
│  └─────────────────┘ └─────────────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                    Repository Layer                         │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐   │
│  │ Customer        │ │ User            │ │ Company      │   │
│  │ Repository      │ │ Repository      │ │ Repository   │   │
│  └─────────────────┘ └─────────────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                     Domain Layer                            │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐   │
│  │ Customer        │ │ User            │ │ Interfaces   │   │
│  │ Entity          │ │ Entity          │ │ & DTOs       │   │
│  └─────────────────┘ └─────────────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 Quick Start

### Prerequisites

- Go 1.23+
- MongoDB 4.4+
- Valid MongoDB connection

### Setup

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

2. **Install dependencies**
   ```bash
   go mod download
   ```

3. **Configure the application**
   ```bash
   cp configs/config.example.yaml configs/config.yaml
   # Edit configs/config.yaml with your settings
   ```

4. **Run database migration**
   ```bash
   go run migrations/001_dual_user_system.go
   ```

5. **Start the server**
   ```bash
   go run cmd/api/main.go
   ```

## 📡 API Endpoints

### Mobile App (Customer) Endpoints

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| POST | `/api/v1/mobile/auth/register` | Customer registration | No |
| POST | `/api/v1/mobile/auth/login` | Customer login | No |
| POST | `/api/v1/mobile/auth/refresh` | Refresh tokens | No |
| POST | `/api/v1/mobile/auth/verify-email` | Email verification | Yes |
| POST | `/api/v1/mobile/auth/change-password` | Change password | Yes |
| GET | `/api/v1/mobile/auth/profile` | Get customer profile | Yes |
| POST | `/api/v1/mobile/auth/logout` | Customer logout | Yes |

### Admin Panel (User) Endpoints

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| POST | `/api/v1/admin/auth/login` | Panel user login | No |
| POST | `/api/v1/admin/auth/refresh` | Refresh tokens | No |
| POST | `/api/v1/admin/auth/change-password` | Change password | Yes |
| GET | `/api/v1/admin/auth/profile` | Get user profile | Yes |
| POST | `/api/v1/admin/users` | Create panel user | Admin only |
| PUT | `/api/v1/admin/users/:id/permissions` | Update permissions | Admin only |

### Legacy Endpoints (Backward Compatible)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/auth/register` | Generic registration (defaults to customer) |
| POST | `/auth/login` | Generic login (tries both types) |
| POST | `/auth/refresh` | Generic token refresh |

## 🔐 Authentication & Authorization

### Token Structure

#### Customer Tokens
```json
{
  "customer_id": "uuid",
  "email": "customer@example.com", 
  "role": "customer_user",
  "company_id": "uuid",
  "user_type": "customer",
  "type": "access"
}
```

#### Panel User Tokens
```json
{
  "user_id": "uuid",
  "email": "admin@example.com",
  "role": "admin", 
  "department": "IT",
  "permissions": ["manage_users", "manage_tenders"],
  "user_type": "user",
  "type": "access"
}
```

### Middleware Options

- `CustomerOnlyMiddleware()` - Mobile users only
- `UserOnlyMiddleware()` - Panel users only  
- `CustomerRoleMiddleware(roles...)` - Customer role-based access
- `UserRoleMiddleware(roles...)` - Panel user role-based access
- `UserPermissionMiddleware(permissions...)` - Fine-grained permissions

### Permission System

Panel users have granular permissions:
- `manage_users` - Create/modify panel users
- `manage_tenders` - Tender management
- `manage_companies` - Company management
- `manage_customers` - Customer management
- `view_reports` - Access reporting
- `manage_system` - System configuration

## 📊 Database Schema

### Collections

- `customers` - Mobile app users
- `users` - Panel users (admin/staff)
- `companies` - Company profiles
- `tenders` - Tender opportunities
- `notifications` - System notifications

### Sample Data

The migration creates sample accounts:

**Admin User:**
- Email: `admin@tendermanagement.com`
- Password: `admin123!`
- Role: `admin`

**Customer:** 
- Email: `customer@example.com`
- Password: `customer123!`
- Role: `customer_user`

## 🛠️ Development

### Project Structure

```
tm/
├── cmd/api/                    # Application entry point
├── internal/
│   ├── domain/                 # Business entities & interfaces
│   ├── service/                # Business logic layer
│   ├── handler/                # HTTP handlers
│   ├── repository/             # Data access layer
│   └── infrastructure/         # External dependencies
├── pkg/
│   ├── logger/                 # Logging utilities
│   ├── middleware/             # HTTP middleware
│   └── response/               # API response utilities
├── configs/                    # Configuration files
├── migrations/                 # Database migrations
└── docs/                       # Documentation
```

### Adding New Features

1. **Define interfaces in domain layer**
2. **Implement business logic in service layer**
3. **Create HTTP handlers**
4. **Add repository implementations**
5. **Wire up in main.go**
6. **Add appropriate middleware to routes**

### Testing

```bash
# Run tests
go test ./...

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

## 🔧 Configuration

Key configuration sections:

```yaml
database:
  mongodb:
    uri: "mongodb://localhost:27017"
    name: "tender_management"

auth:
  jwt:
    secret: "your-jwt-secret"
    access_token_duration: "15m"
    refresh_token_duration: "7d"

server:
  host: "localhost"
  port: 8080
  timeout: "30s"
```

## 🚨 Security Features

- **Separate Authentication**: Isolated customer and panel user auth
- **JWT Tokens**: Stateless authentication with refresh tokens
- **Password Hashing**: bcrypt with configurable cost
- **Role-Based Access**: Granular role and permission system
- **Input Validation**: Comprehensive request validation
- **CORS Support**: Configurable cross-origin policies

## 📈 Monitoring & Logging

- **Structured Logging**: JSON-formatted logs with context
- **Request Logging**: HTTP request/response logging
- **Error Tracking**: Contextual error information
- **Health Checks**: `/health` endpoint for monitoring

## 🎯 Key Benefits

1. **Clear Separation**: Mobile and panel users are completely isolated
2. **Security**: Each user type has appropriate authentication and authorization
3. **Scalability**: Clean architecture allows easy feature additions
4. **Maintainability**: Well-structured code with clear dependencies
5. **Backward Compatibility**: Legacy endpoints continue to work
6. **Developer Friendly**: Comprehensive logging and error handling

## 📚 Next Steps

- [ ] Implement CompanyRepository
- [ ] Add tender management endpoints
- [ ] Create notification system
- [ ] Add file upload functionality
- [ ] Implement email verification
- [ ] Add rate limiting
- [ ] Create API documentation with Swagger
- [ ] Add comprehensive test coverage