tm_back/README.md

# Tender Management System

A comprehensive tender management backend system built with Go, following Clean Architecture principles with Domain-Driven Design (DDD) patterns.

## 📚 Documentation

All documentation has been organized in the [`docs/`](./docs/) directory for better structure and maintainability.

### Quick Links
- **[📖 Main Documentation](./docs/README.md)** - Comprehensive project overview and guidelines
- **[🔧 Setup Guides](./docs/setup/)** - HTTP server and Swagger setup
- **[🚀 Implementation Details](./docs/implementation/)** - Architecture and implementation overview
- **[📡 API Examples](./docs/examples/)** - API usage examples and endpoints

## 🚀 Quick Start

1. **Setup Environment**
   ```bash
   # Follow setup guides in docs/setup/
   ```

2. **Run the Application**
   ```bash
   make run
   ```

3. **Access API Documentation**
   - Swagger UI: `http://localhost:8081/swagger/index.html`
   - API Base URL: `http://localhost:8081/api/v1`

## 🏗️ Architecture

This system implements **Clean Architecture** with:
- **Domain Layer**: Business entities and core rules
- **Service Layer**: Business logic and use cases
- **Handler Layer**: HTTP controllers and request handling
- **Repository Layer**: Data access implementations
- **Infrastructure Layer**: External dependencies

## 📋 Key Features

- **Clean Architecture**: DDD principles with clear separation of concerns
- **MongoDB Integration**: Robust data persistence with proper indexing
- **Structured Logging**: Comprehensive logging with context
- **Input Validation**: Govalidator integration for request validation
- **Error Handling**: Consistent error responses and logging
- **Time Handling**: Unix timestamps throughout the application
- **API Documentation**: Auto-generated Swagger documentation

## 📋 API Documentation

### Swagger/OpenAPI 3.0 Documentation

The Tender Management API features comprehensive, auto-generated Swagger documentation with:

#### 🚀 **Version 2.0.0 Features**
- **Comprehensive API Coverage**: All endpoints documented with detailed descriptions, examples, and error responses
- **Interactive API Testing**: Built-in Swagger UI for testing endpoints directly from the documentation
- **Authentication Integration**: Bearer token authentication examples and testing capability
- **Request/Response Examples**: Real-world examples for all data structures and API calls
- **Error Documentation**: Detailed error codes, messages, and troubleshooting information

#### 📊 **API Endpoints Categories**
- **Health**: System monitoring and health check endpoints
- **Authorization**: User authentication, token management, and session handling
- **Users**: Administrative user management with RBAC (Role-Based Access Control)
- **Customers-Admin**: Web panel customer management with advanced filtering
- **Customers-Authorization**: Mobile app customer authentication and profile access
- **Companies-Admin**: Comprehensive company management with search, filtering, and analytics
- **Companies-Mobile**: Mobile-optimized company lookup and information retrieval

#### 🔧 **Documentation Access**
- **Local Development**: `http://localhost:8081/swagger/`
- **Interactive Testing**: All endpoints can be tested directly from the Swagger UI
- **Authentication**: Use the "Authorize" button to set Bearer tokens for protected endpoints
- **Export Options**: JSON and YAML formats available for API specifications

#### 📝 **Enhanced Features**
- **Detailed Descriptions**: Each endpoint includes comprehensive business logic explanations
- **Parameter Validation**: Complete validation rules and constraints for all input parameters
- **Response Examples**: Real-world response examples with proper HTTP status codes
- **Security Schemes**: JWT Bearer token authentication clearly documented
- **Error Handling**: Comprehensive error response documentation with troubleshooting guides
- **Filtering & Pagination**: Advanced query parameters for list endpoints with examples
- **Business Logic**: Context-aware descriptions explaining when and how to use each endpoint

#### 🏗️ **Technical Specifications**
- **OpenAPI/Swagger 2.0**: Industry-standard API documentation format
- **Auto-Generation**: Documentation automatically updated from code annotations
- **Type Safety**: Strong typing with Go struct validation and examples
- **Validation Rules**: Complete govalidator integration for request validation
- **Consistent Response Format**: Standardized API response structure with metadata

#### 💡 **Usage Examples**
```bash
# Access Swagger UI
curl http://localhost:8081/swagger/

# Download API specification
curl http://localhost:8081/swagger/doc.json

# Test authentication endpoint
curl -X POST "http://localhost:8081/admin/v1/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'
```

#### 🔐 **Authentication Testing**
1. Navigate to Swagger UI at `/swagger/`
2. Click "Authorize" button
3. Enter: `Bearer <your_jwt_token>`
4. Test protected endpoints directly from the interface

### API Design Principles
- **RESTful Design**: Consistent REST principles with proper HTTP methods and status codes
- **Clean Architecture**: Domain-driven design with clear separation of concerns
- **Validation**: Comprehensive input validation with meaningful error messages
- **Security**: JWT-based authentication with proper token management
- **Performance**: Optimized queries with pagination and filtering capabilities
- **Maintainability**: Auto-generated documentation stays in sync with code changes

## 🔧 Development

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

### Project Structure
```
tm_back/
├── cmd/web/                    # Application entry point
├── internal/                   # Private application code
│   ├── customer/              # Customer domain
│   └── ...                    # Other domains
├── pkg/                       # Public packages
│   ├── logger/               # Logging utilities
│   ├── mongo/                # MongoDB utilities
│   └── response/             # API response utilities
├── docs/                      # 📚 All documentation
└── config.yaml               # Configuration file
```

## 📞 Support

For detailed documentation, guides, and examples, please visit the [`docs/`](./docs/) directory.

---

**Version**: 1.0.0  
**Last Updated**: $(date)