Skip to content

Fat1512/XCity-Smart-City-System

BranchesTags

Repository files navigation

XCity Smart City System

🌆 X-City Smart City System

📖 Mục lục

🌟 Giới thiệu

X-City là dự án mã nguồn mở hướng tới việc xây dựng một hệ sinh thái thành phố thông minh, phục vụ cư dân và nhà quản lý:

  • Tận dụng AI & IoT để giám sát môi trường, giao thông và hạ tầng theo thời gian thực.
  • Quản lý và phân tích dữ liệu realtime, cảnh báo sớm các sự cố và tắc nghẽn.
  • Hỗ trợ ra quyết định thông minh, tối ưu hóa vận hành và nâng cao chất lượng cuộc sống.

Link thuyết trình cho dự án: Fenwick Presentation

⚡ Các tính năng chính

  • Nhận diện lưu lượng giao thông realtime bằng camera AI (YOLO)
  • Phân tích dòng phương tiện, cảnh báo tắc đường, đưa ra gợi ý tuyến di chuyển tối ưu
  • Kết nối sensor IoT, API bên ngoài (OpenAQ) - hiển thị dữ liệu, cảnh báo ô nhiễm
  • Cảnh báo tai nạn, thiên tai, sự cố tới cư dân và quản lý đô thị
  • Dashboard realtime, phân tích dữ liệu & ra quyết định
  • Trợ lý ảo hỗ trợ cung cấp các thông tin trong thành phố

📂 Cấu trúc thư mục

PMNM/
│
├── 🤖 AI/                                 # Hệ thống AI & Machine Learning cho Smart City
│   ├── app/
│   ├── components/                         # Các thành phần AI riêng biệt
|   │   ├── database/
|   │   ├── embedding/                      # Xử lý embedding cho dữ liệu (vector, hình...)
|   │   ├── generation/                     # Sinh dữ liệu hoặc nội dung tự  động (AI generation, prompt)
|   │   ├── ingest_strategy/
|   │   ├── logging/                        # Ghi lại lịch sử vận hành AI
|   │   ├── reader/
|   │   ├── tools/
|   |   │   ├── route/                      # Xử lý việc chỉ đường
|   |   |   ├── traffic_monitor/            # Giám sát giao thông, phân tích hình ảnh camera
|   │   ├── watcher/
|   │   ├── interfaces.py
|   │   ├── manager.py
│   ├── config/                             # Thiết lập cấu hình cho giả lập camera
│   ├── prompt/                             # Quản lý prompt AI, LLM,...
│   ├── service/                            # Business logic nghiệp vụ chính
│   └── requirements.txt
│
├── 📊 Data/
│   ├── airflow/
│       ├── dags/
│       └── config/                         # Cấu hình Airflow
|
├── 💻 FE/                                 # Frontend: giao diện dashboard cho cư dân & QL thành phố
│   ├── public/
│   ├── src/
│   │   ├── context/                        # Quản lý state tổng (React context)
│   │   ├── feature/                        # Tính năng riêng biệt của FE (traffic, air quality,...)
│   │   ├── global/
│   │   ├── page/                           # Trang chính giao diện
│   │   ├── service/                        # Gọi API backend, quản lý request dữ liệu
│   │   ├── types/                          # TypeScript type, interface cho FE
│   │   ├── ui/                             # Component UI tái sử dụng
│   │   ├── utils/
│   │   └── App.tsx                         # Root của ứng dụng React
|
├── 📡 SensorService/                       # IoT giả lập cảm biến đô thị
│
├── 🏢 XCityServer/                         # Backend chính
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   │   └── com/xcity/tpd/XCity
│   │   │   │       ├── controller/         # Cung cấp REST API cho hệ thống
│   │   │   │       ├── service/            # Business logic nghiệp vụ chính
│   │   │   │       ├── repository/         # Truy xuất dữ liệu, kết nối DB
│   │   │   │       ├── dto/
│   │   │   │       ├── mapper/
│   │   │   │       ├── filter/             # Xử lý request/response, xác thực, logging, lọc dữ liệu
│   │   │   │       ├── entity/             # Định nghĩa entity
│   │   │   │       ├── config/
│   │   │   └── resources/
│   │   │       └── application.yml
│   │   └── test/
│   └── pom.xml
│
└── 🐳 Dockerfile
│
└── 🐳 airflow-docker-compose.yml            # Docker compose cho Airflow
│
└── 🐳 docker-compose.yml                    # Docker compose cho toàn bộ hệ thống

🛠 Tech Stack

Thành phần Công nghệ & Mục đích
Backend Spring Boot, FastAPI, Orion-LD
Frontend React, TypeScript, Tailwind CSS
AI/ML YOLO-NAS
Data/IoT Mosquitto MQTT, Airflow
Infra Docker, Docker Compose, GCP

🏗️ Kiến trúc hệ thống

architecture

💻 Bảng cổng (Port) sử dụng

Thành phần Mô tả Port mặc định
XCityServer Backend chính API đô thị 8090
SensorService Service giả lập cảm biến IoT 5000
AI Service Service camera giao thông AI 5001
FE Web giao diện người dân / quản lý 5173
Mosquitto MQTT Broker Kết nối, publisher/subscriber IoT 1883 (TCP)
Orion-LD Context Broker / cơ sở dữ liệu ngữ cảnh 1026
Airflow Web UI Quản lý pipeline 8080
IoT Agent Quản lý IoT Agent 4041
MongoDB Cơ sở dữ liệu lưu trữ 27017

Lưu ý:

  • Có thể chỉnh lại port qua file cấu hình hoặc docker-compose.
  • Xem docker-compose.yml và từng service để xác nhận port nếu thay đổi.

🌐 Các endpoint chính

Tài liệu API

Method Endpoint Request Body / Params Description
GET /air/monthly-statics sensorId, year, month Lấy thống kê chất lượng không khí theo tháng
GET /air/daily-statics sensorId, date Lấy thống kê chất lượng không khí theo ngày
GET /alert/statics type Thống kê các SoS, thông báo
GET /alert/download type Tải dữ liệu alert để download
POST /traffic/download-statics/ Map<String, Object> Tải thống kê giao thông
GET /traffic/daily-statics/{cameraId} date Lấy thống kê giao thông theo ngày cho camera

🚀 Thiết lập dự án

1️⃣ Chuẩn bị môi trường

  • Docker & Docker Compose
  • Node.js >= 18.x
  • Python >= 3.8 (3.9+ recommended)
  • Java >= 17 (for XCityServer)

2️⃣ Clone repo

git clone https://github.com/Fat1512/XCity-Smart-City-System.git
cd XCity-Smart-City-System

3️⃣ Chạy từng thành phần (quickstart)

Các dịch vụ cần thiết khác

docker compose -f service-docker-compose.yml up -d

Sensor Service

cd SensorService
python -m venv .venv
source .venv/bin/activate  # hoặc .venv\Scripts\Activate.ps1 trên Windows
pip install -r requirements.txt
python app.py

Frontend

Thiết lập các biến môi trường cho front-end

VITE_BASE_URL=http://localhost:8090/xcity-service/api/v1
VITE_SENSOR_URL=http://127.0.0.1:5000/sensor
VITE_AI_URL=http://localhost:5000/api/
VITE_MAPBOX_TOKEN=your-mapbox-token
VITE_CAMERA_AI_URL=ws://localhost:5001/ws/frontend
cd FE
npm install
npm run dev

XCity Server

Thiết lập các biến môi trường cho server

CLIENT_URL=http://localhost:5173
MONGO_URL=mongodb://yourusername:yourpassword@localhost:27017/xcity?authSource=admin
AUTH_SECRET_KEY=your-secret-key
AI_SERVER_URL=http://localhost:5001/api
ORION_LD_URL=http://localhost:1026/ngsi-ld/v1/entities
SENSOR_SERVICE=http://127.0.0.1:5000/sensor
IOT_AGENT=http://localhost:4041/iot
cd XCityServer
./mvnw spring-boot:run

AI Service

Thiết lập các biến môi trường cho AI service

AI_HOST=localhost:5001

LLM_PROVIDER=openai
OPENAI_MODEL=gpt-4o-mini
OPENAI_API_KEY=your_openai_api_key
# LLM_PROVIDER=ollama
# OLLAMA_MODEL=llama3.2:3b
# OLLAMA_HOST=http://10.1.1.237:11434/

ORION_URL = "http://localhost:1026"


# EMBEDDING_PROVIDER=ollama
# EMBEDDING_MODEL_NAME=nomic-embed-text:latest
EMBEDDING_PROVIDER=sentence_transformer
EMBEDDING_MODEL_NAME=bkai-foundation-models/vietnamese-bi-encoder

# REDIS_HOST=localhost
# REDIS_PORT=6739
# REDIS_USERNAME=
# REDIS_PASSWORD=

AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
AWS_DEFAULT_REGION=ap-southeast-2

WATCHER_S3_BUCKET=tadel-media
WATCHER_S3_PREFIX=rss/
WATCHER_S3_INTERVAL=60

WATCHER_RSS_URLS=https://vnexpress.net/rss/thoi-su.rss
WATCHER_RSS_INTERVAL=60

KNOWLEDGE_S3_ENABLED=true
KNOWLEDGE_RSS_ENABLED=true

# Config
MONGO_URI=mongodb://tanle92:090224Tan@localhost:27017/xcity?authSource=admin

# Reranker
RERANKER_PROVIDER=jina
RERANK_THRESHOLD=0.1
10.1.1.237

cd AI
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

uvicorn run:app --host 0.0.0.0 --port 5001 --ws-max-size 20000000

Tạo các Subscription cho server nhận các thay đổi từ Orion-ld

Subscription cho AirQualityObserved

curl -X POST "http://localhost:1026/ngsi-ld/v1/subscriptions" \
  -H "Content-Type: application/json" \
  -H "Fiware-Service: openiot" \
  -H "Fiware-ServicePath: /" \
  -d '{
    "type": "Subscription",
    "description": "Subscription for Air Quality changes",
    "entities": [
        {
            "type": "AirQualityObserved"
        }
    ],
    "watchedAttributes": [
        "pm25",
        "pm1",
        "o3",
        "temperature",
        "refDevice"
    ],
    "notification": {
        "attributes": [
            "pm25",
            "pm1",
            "o3",
            "temperature",
            "refDevice"
        ],
        "endpoint": {
            "uri": "http://host.docker.internal:8090/xcity-service/api/v1/air/notify", # URL server nhận notification
            "accept": "application/json"
        },
        "format": "keyValues"
    },
    "@context": "https://smart-data-models.github.io/dataModel.Environment/context.jsonld"
}'

Subscription cho TrafficFlowObserved

curl -X POST "http://localhost:1026/ngsi-ld/v1/subscriptions" \
  -H "Content-Type: application/json" \
  -d '{
   "type": "Subscription",
        "description": "Subscription for Air Quality changes",
        "entities": [
            {
                "type": "TrafficFlowObserved"
            }
        ],
        "watchedAttributes": [
            "averageVehicleSpeed",
            "intensity",
            "occupancy",
            "congested",
            "refDevice"
        ],
        "status": "active",
        "isActive": true,
        "notification": {
            "attributes": [
                "averageVehicleSpeed",
                "intensity",
                "occupancy",
                "congested",
                "refDevice"
            ],
            "format": "keyValues",
            "endpoint": {
                "uri": "http://host.docker.internal:8090/xcity-service/api/v1/traffic/notify", # URL server nhận notification
                "accept": "application/json"
            },
            "status": "ok"
        },
        "@context": "https://smart-data-models.github.io/dataModel.Transportation/context.jsonld"
}'

Khởi chạy Airflow

  docker compose -f airflow-docker-compose.yaml up -d

4️⃣ Docker & compose

Thiết lập các biến môi trường

MONGO_URL=your-url
AUTH_SECRET_KEY=your-secret-key
MAPBOX_TOKEN=your-token
docker compose up -d

Đóng góp cho dự án

Bug Report ⚠️

Request Feature 👩‍💻

Nếu bạn muốn đóng góp cho dự án, vui lòng tham khảo CONTRIBUTING.md để biết thêm chi tiết.

Mọi đóng góp đều được trân trọng, vì vậy đừng ngần ngại gửi pull request tới dự án.

Liên hệ

Giấy phép

Dự án này được cấp phép theo APACHE-2.0

Tác giả

About

https://xcity.tanle.site

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 2

v1.0.0 Latest
Dec 10, 2025
+ 1 release

Packages

 
 
 

Contributors

Languages