Skip to content

UITgo/architecture

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

30 Commits
ADR
ADR
 
 
asset
asset
 
 
ARCHITECTURE.md
ARCHITECTURE.md
 
 
README.md
README.md
 
 
REPORT.md
REPORT.md
 
 
SERVICE-FLOWS.md
SERVICE-FLOWS.md
 
 

Repository files navigation

🚖 UITGo

Cloud-Native Ride-Hailing Platform built with Microservices, CQRS, Kafka, Redis Geo, and Event-Driven Architecture

Architecture Pattern Streaming Redis Communication Deployment Testing

✨ System Highlights

  • 🚖 Real-time Ride Matching
  • ⚡ Kafka Event Streaming
  • 🌍 Regional Sharding (HCM / HN)
  • 📦 CQRS Architecture
  • 📍 Redis Geo Spatial Queries
  • 🔐 JWT Authentication
  • 🚀 Dockerized Infrastructure
  • 📊 Load Tested with k6

1. Giới thiệu UITGo

UITGo là một hệ thống gọi xe được phát triển dựa trên kiến trúc microservices, cung cấp các chức năng cốt lõi như đặt chuyến, tìm tài xế gần nhất, quản lý vị trí và trạng thái tài xế theo thời gian thực. Hệ thống được thiết kế để hỗ trợ mở rộng theo từng khu vực địa lý (HCM, HN) và tối ưu hóa cho cả read-heavy workloads (truy vấn dữ liệu) và write-heavy workloads (cập nhật vị trí tài xế).

Repo architecture này đóng vai trò là "cửa chính" (entry point) của toàn bộ hệ thống UITGo. Repo này chứa:

  • Tài liệu kiến trúc tổng thể (ARCHITECTURE.md)
  • Báo cáo chuyên sâu Module A (REPORT.md)
  • Architectural Decision Records (ADR/) - 18 quyết định thiết kế quan trọng
  • Bảng danh mục và liên kết đến tất cả các service/repo trong hệ thống

🏗 System Architecture

UITGo sử dụng kiến trúc microservices với các pattern:

  • API Gateway Pattern: Single entry point cho tất cả clients
  • Database-per-Service: Mỗi service có database riêng (PostgreSQL, MongoDB)
  • CQRS: Trip service tách thành command (write) và query (read)
  • Event-Driven Architecture: Kafka cho real-time event streaming
  • Sharding: Driver-stream được shard theo region (HCM, HN)
  • Caching: Redis cho read-heavy paths và Redis Geo cho spatial queries

🛠 Technology Stack

Layer Technologies
Backend NestJS, Go
Communication REST, gRPC, Kafka
Database PostgreSQL, MongoDB
Caching Redis, Redis Geo
Infrastructure Docker Compose
Observability Logging, Metrics
Testing k6

🧩 Service Landscape

Component Repo / Folder Technology / Description
API Gateway gateway-service NestJS, expose /api/v1/*, JWT authentication, request routing
Auth Service auth-service NestJS, AWS Cognito integration, JWT token generation
User Service user-service NestJS + MongoDB, user profile management, gRPC service
Trip Command trip-command-service NestJS + PostgreSQL, CQRS write side, region sharding
Trip Query trip-query-service NestJS + PostgreSQL + Redis, CQRS read side, caching
Driver Stream driver-stream Go + Redis Geo + Kafka, driver location & status, trip assignment
Infrastructure infra Docker Compose, k6 load testing scripts, infrastructure configs
Proto Contracts proto gRPC/Protobuf definitions cho inter-service communication
IaC iac Terraform/Bicep cho AWS infrastructure
Frontend User fe-user Frontend cho passenger app
Frontend Driver fe-driver Frontend cho driver app
Architecture Docs architecture Tài liệu: README, ARCHITECTURE.md, REPORT.md, ADR/

3. Tài liệu kiến trúc & báo cáo

ARCHITECTURE.md

Mô tả chi tiết kiến trúc hệ thống UITGo, bao gồm:

  • Kiến trúc tổng thể (microservices, communication patterns)
  • Kiến trúc Module A (trip flow, driver-stream flow, CQRS, sharding)
  • Technology stack và lý do lựa chọn
  • Database schema và data flow

REPORT.md

Báo cáo chuyên sâu Module A (3-5 trang), bao gồm:

  • Phân tích kiến trúc hệ thống
  • In-depth analysis của Module A (CQRS, Redis cache, Redis Geo, sharding, k6)
  • Architectural decisions và trade-offs
  • Challenges và lessons learned
  • Results và future development

ADR/

Thư mục chứa 18 Architectural Decision Records, mỗi ADR document một quyết định thiết kế quan trọng:

  • ADR-001: Architecture Style - Microservices
  • ADR-002: Communication - REST, gRPC, Kafka
  • ADR-003: Driver Location - Redis Geo vs DynamoDB
  • ADR-004: Authentication - Gateway vs Per-Service JWT
  • ADR-005: Trip Read Path - Cache Redis, CQRS
  • ADR-006: Driver Stream - Sharding by Region
  • ADR-007: Database Choice - PostgreSQL vs MongoDB
  • ADR-008: Message Queue - Kafka vs RabbitMQ
  • ADR-009: Caching Strategy - Redis vs Memcached
  • ADR-010: API Gateway Pattern
  • ADR-011: Container Orchestration - Docker Compose
  • ADR-012: Error Handling and Retry Strategy
  • ADR-013: Monitoring and Observability Strategy
  • ADR-014: Data Consistency - Eventual Consistency
  • ADR-015: Testing Strategy - Unit, Integration, Load Testing
  • ADR-016: Security - JWT vs OAuth2
  • ADR-017: Rate Limiting Strategy
  • ADR-018: Deployment Strategy - Blue-Green vs Rolling

Mỗi ADR theo format chuẩn: Title, Status, Date, Context, Decision, Consequences.

4. Cách bắt đầu đọc & chạy hệ thống

Bước 1: Đọc tài liệu kiến trúc

Để hiểu tổng quan về hệ thống, hãy đọc theo thứ tự:

  1. README - Entry point, tổng quan về các components
  2. ARCHITECTURE.md - Kiến trúc chi tiết, technology stack, data flow
  3. REPORT.md - Báo cáo chuyên sâu Module A, challenges, results
  4. ADR/ - Các quyết định thiết kế (đọc theo thứ tự ADR-001 → ADR-018)

Bước 2: Clone các service repositories

Sau khi hiểu kiến trúc, clone các service repositories cần thiết:

# Clone các service chính
git clone https://github.com/UITgo/gateway-service
git clone https://github.com/UITgo/auth-service
git clone https://github.com/UITgo/user-service
git clone https://github.com/UITgo/trip-service
git clone https://github.com/UITgo/driver-stream

# Clone infrastructure
git clone https://github.com/UITgo/infra
git clone https://github.com/UITgo/proto

Vì nhóm tổ chức multi-repo github.

Bước 3: Chạy hệ thống local với Docker Compose

Để demo hệ thống local, vào repo infra và chạy:

cd infra
docker compose up

Lệnh này sẽ khởi động:

  • Infrastructure: PostgreSQL, MongoDB, Redis, Kafka, OSRM
  • Services: gateway-service, auth-service, user-service, trip-command-service, trip-query-service, driver-stream-hcm, driver-stream-hn

Sau khi các service đã start, kiểm tra health:

# Gateway
curl http://localhost:3004/healthz

# Trip Command
curl http://localhost:3002/healthz

# Trip Query
curl http://localhost:3003/healthz

Xem hướng dẫn chi tiết trong infra/README.md.

Bước 4: Test API

1. Đăng nhập để lấy JWT token:

curl -X POST http://localhost:3004/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password"
  }'

2. Tạo trip:

curl -X POST http://localhost:3004/api/v1/trips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -d '{
    "origin": { "lat": 10.8231, "lng": 106.6297 },
    "destination": { "lat": 10.7626, "lng": 106.6602 },
    "cityCode": "HCM",
    "note": "Test trip"
  }'

3. Lấy thông tin trip (sử dụng Redis cache):

curl -X GET http://localhost:3004/api/v1/trips/<tripId> \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

Xem thêm examples trong README của từng service.

Load Testing với k6

Các script k6 nằm trong infra/k6/:

  • trips_create.js: Test latency của create trip flow
  • drivers_update_location.js: Test throughput của location updates
  • trips_read_cached.js: Test read-heavy scenario với cache

Chạy một script:

cd infra/k6
k6 run trips_create.js

5. Yêu cầu môi trường

  • Node.js: >= 20.x
  • Go: >= 1.22
  • Docker: >= 20.x
  • Docker Compose: >= 2.x
  • k6: >= 0.47.0 (để chạy load test)

6. Cấu trúc repository

UITGo/
├── architecture/          # Repo này - tài liệu kiến trúc
│   ├── README.md          # Entry point (file này)
│   ├── ARCHITECTURE.md    # Kiến trúc chi tiết
│   ├── REPORT.md          # Báo cáo cuôi kỳ
│   └── ADR/               # Architectural Decision Records
├── gateway-service/        # API Gateway
├── auth-service/          # Authentication service
├── user-service/          # User profile service
├── trip-service/
│   ├── trip-command-service/  # Trip write (CQRS)
│   └── trip-query-service/    # Trip read (CQRS + cache)
├── driver-stream/         # Driver location & status
├── infra/                 # Docker Compose, k6
├── proto/                 # gRPC proto files
└── iac/                   # Infrastructure as Code (Terraform)

7. Liên kết nhanh

About

This repository stores all system-level documentation for the UIT-Go Cloud-Native platform.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors