@tasolutions/express-core/PROJECT_OVERVIEW.md

All libs for express

# Tổng quan dự án Core API

## Giới thiệu

Core API là một thư viện nền tảng được thiết kế để làm cơ sở cho việc phát triển các API khác. Thư viện này cung cấp các thành phần cơ bản, tiện ích và cấu trúc chung để đảm bảo tính nhất quán, hiệu quả và bảo mật trong quá trình phát triển API.

## Kiến trúc tổng thể

Core API được xây dựng với kiến trúc module hóa cao, cho phép các dự án tích hợp chỉ những thành phần cần thiết. Các thành phần chính bao gồm:

1. **Hệ thống xác thực và phân quyền**
   - Hỗ trợ nhiều phương thức xác thực (JWT, OAuth, API Key)
   - Quản lý phân quyền chi tiết
   - Bảo mật và chống tấn công phổ biến

2. **Quản lý cơ sở dữ liệu**
   - Kết nối và quản lý pool connections
   - Hỗ trợ nhiều loại database (SQL, NoSQL)
   - Query builders và ORM integration
   - Transaction management

3. **Caching**
   - In-memory cache
   - Distributed cache (Redis)
   - Cache strategies và invalidation

4. **Logging và Monitoring**
   - Structured logging
   - Performance monitoring
   - Error tracking
   - Audit logs

5. **Xử lý lỗi**
   - Standardized error handling
   - Error classification
   - Custom error types
   - Error middleware

6. **Validation**
   - Input validation
   - Schema validation
   - Data sanitization

7. **Middleware**
   - Security middleware
   - Compression
   - Rate limiting
   - CORS
   - Body parsing

8. **Utilities**
   - Date/time handling
   - String manipulation
   - File operations
   - Encryption/Decryption
   - Hashing

## Cấu trúc dự án

```
/
├── src/                           # Mã nguồn chính
│   ├── auth/                      # Xác thực và phân quyền
│   │   ├── strategies/            # Các chiến lược xác thực
│   │   ├── middleware/            # Middleware xác thực
│   │   └── utils/                 # Tiện ích xác thực
│   ├── cache/                     # Hệ thống cache
│   │   ├── providers/             # Các provider cache
│   │   ├── strategies/            # Chiến lược cache
│   │   └── middleware/            # Middleware cache
│   ├── config/                    # Cấu hình
│   │   ├── environments/          # Cấu hình theo môi trường
│   │   ├── loaders/               # Config loaders
│   │   └── validators/            # Config validators
│   ├── database/                  # Kết nối và quản lý database
│   │   ├── connectors/            # Database connectors
│   │   ├── migrations/            # Migration utilities
│   │   └── transactions/          # Transaction handling
│   ├── errors/                    # Xử lý lỗi
│   │   ├── types/                 # Các loại lỗi
│   │   ├── handlers/              # Error handlers
│   │   └── middleware/            # Error middleware
│   ├── logging/                   # Ghi log
│   │   ├── adapters/              # Log adapters
│   │   ├── formatters/            # Log formatters
│   │   └── middleware/            # Logging middleware
│   ├── middleware/                # Middleware
│   │   ├── security/              # Security middleware
│   │   ├── performance/           # Performance middleware
│   │   └── common/                # Common middleware
│   ├── models/                    # Các model chung
│   ├── utils/                     # Tiện ích
│   │   ├── crypto/                # Cryptographic utilities
│   │   ├── date/                  # Date utilities
│   │   ├── string/                # String utilities
│   │   └── file/                  # File utilities
│   └── validation/                # Xác thực dữ liệu
│       ├── schemas/               # Validation schemas
│       ├── middleware/            # Validation middleware
│       └── sanitizers/            # Data sanitizers
├── tests/                         # Unit tests và integration tests
│   ├── unit/                      # Unit tests
│   ├── integration/               # Integration tests
│   └── fixtures/                  # Test fixtures
├── examples/                      # Ví dụ sử dụng thư viện
│   ├── basic-api/                 # API cơ bản
│   ├── auth-example/              # Ví dụ về xác thực
│   └── full-featured/             # Ví dụ đầy đủ tính năng
└── docs/                          # Tài liệu
    ├── api/                       # Tài liệu API
    ├── architecture/              # Tài liệu kiến trúc
    ├── components/                # Tài liệu thành phần
    └── guidelines/                # Hướng dẫn và quy tắc
```

## Quy trình phát triển

Core API tuân theo quy trình phát triển nghiêm ngặt để đảm bảo chất lượng và tính ổn định:

1. **Phát triển tính năng**
   - Phát triển trên nhánh feature riêng biệt
   - Tuân thủ coding standards
   - Viết unit tests và integration tests

2. **Code Review**
   - Pull Request review
   - Code quality checks
   - Test coverage verification

3. **Testing**
   - Automated testing
   - Performance testing
   - Security testing

4. **Release**
   - Semantic versioning
   - Changelog generation
   - Documentation updates

## Tích hợp và sử dụng

Core API được thiết kế để dễ dàng tích hợp vào các dự án khác:

1. **Cài đặt thư viện**
   ```bash
   npm install @9s/core-api
   ```

2. **Cấu hình cơ bản**
   ```javascript
   const { createApp } = require('@9s/core-api');
   
   const app = createApp({
     auth: {
       strategy: 'jwt',
       secret: process.env.JWT_SECRET
     },
     database: {
       type: 'postgres',
       url: process.env.DATABASE_URL
     },
     // Các cấu hình khác
   });
   
   app.start();
   ```

3. **Sử dụng các module**
   ```javascript
   const { auth, db, validation } = require('@9s/core-api');
   
   // Sử dụng authentication
   app.use(auth.middleware.jwt());
   
   // Sử dụng database
   const users = await db.query('SELECT * FROM users');
   
   // Sử dụng validation
   app.use(validation.middleware.validate(userSchema));
   ```

## Tài liệu tham khảo

- [Hướng dẫn API](docs/api/README.md)
- [Kiến trúc chi tiết](docs/architecture/README.md)
- [Hướng dẫn tích hợp](docs/implementation-guide/README.md)
- [Các thành phần](docs/components/README.md)

---

*Tài liệu này sẽ được cập nhật thường xuyên khi có thay đổi hoặc tính năng mới.*