fastapi-modular 0.1.0__tar.gz

fastapi_modular-0.1.0/.gitignore

@@ -0,0 +1,88 @@
+# ---------------------------------------------------------------- Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Gói và bản dựng
+build/
+dist/
+sdist/
+wheels/
+*.egg
+*.egg-info
+.eggs/
+MANIFEST
+pip-wheel-metadata/
+
+# Môi trường ảo
+.venv/
+venv/
+ENV/
+env/
+.python-version
+
+# Test, độ phủ, kiểm kiểu, lint
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+.pytype/
+.pyre/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+*.cover
+.hypothesis/
+.cache/
+
+# Jupyter
+.ipynb_checkpoints/
+profile_default/
+ipython_config.py
+
+# ------------------------------------------------------------- Dự án này
+# .env chứa DSN và mật khẩu thật — KHÔNG BAO GIỜ commit.
+.env
+.env.*
+!.env.example
+
+data/
+*.db
+*.sqlite
+*.sqlite3
+*.log
+logs/
+
+# ------------------------------------------------------------------- IDE
+.idea/
+.vscode/
+# Muốn chia sẻ cấu hình cho cả nhóm thì bỏ dòng .vscode/ ở trên và ignore
+# từng file: .vscode/* rồi !.vscode/settings.json, !.vscode/extensions.json
+.fleet/
+.zed/
+*.sublime-project
+*.sublime-workspace
+*.swp
+*.swo
+*~
+.\#*
+\#*\#
+
+# --------------------------------------------------------- Hệ điều hành
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# --------------------------------------------------------------- Công cụ
+.direnv/
+node_modules/

fastapi_modular-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Thay đổi
+
+Theo [Keep a Changelog](https://keepachangelog.com/vi/1.1.0/); phiên bản theo
+[SemVer](https://semver.org/lang/vi/).
+
+## [Chưa phát hành]
+
+### Sửa
+
+- `pym lint` không tham số trỏ vào thư mục `app` không tồn tại nên lỗi ngay;
+  mặc định đổi thành `src`, đúng thứ `pym init` sinh ra.
+
+## [0.1.0] — 2026-08-21
+
+Bản đầu tiên. Cần **Python 3.10 trở lên**.
+
+### Có gì
+
+- **Kiến trúc module kiểu NestJS**: DI container (`@injectable`, `Lazy[...]`,
+  `Scope.REQUEST`), controller dạng class (`@controller`, `@get`/`@post`/...),
+  tự quét module — thêm thư mục là có route, không phải đăng ký ở đâu cả.
+- **Repository dùng chung cho 4 backend**: memory, SQLite, PostgreSQL, MongoDB.
+  Đổi backend không phải sửa service. Kèm circuit breaker và hạn thời gian.
+- **WebSocket**: `@gateway` / `@subscribe`, phòng, gửi thẳng tới một người,
+  nhịp tim, giới hạn tần suất, adapter Redis để phát tin xuyên worker.
+- **Bốn lớp hạ tầng tuỳ chọn, cùng một khuôn**: RabbitMQ, Redis, MQTT, Kafka.
+  Mặc định TẮT; thư viện chỉ được import khi bật. Tất cả tự nối lại.
+- **CLI** `pymodular`, gõ tắt là `pym`: `init` (dựng dự án ngay trong thư mục
+  hiện tại) · `new` · `dev` / `run` · `module` · `env` · `info` · `migrate` ·
+  `test` / `lint`. `init` không bao giờ ghi đè file đã có.
+- **Tài liệu tiếng Việt** trong `docs/`, viết theo lối tra cứu: mỗi hàm nói rõ
+  truyền gì, không truyền thì mặc định là gì.

fastapi_modular-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oryza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_modular-0.1.0/Makefile

@@ -0,0 +1,118 @@
+VENV := .venv
+PY   := $(VENV)/bin/python
+PIP  := $(PY) -m pip
+
+# Nạp .env để make dùng chung biến với app (pydantic Settings cũng đọc file này).
+-include .env
+export
+
+APP_HOST ?= 0.0.0.0
+APP_PORT ?= 8000
+
+.DEFAULT_GOAL := help
+.PHONY: help dev run test lint lint-fix module gateway consumer migrate migrate-create migrate-down migrate-history migrate-sql install install-dev install-sqlite install-postgres install-mongo install-redis install-ws-redis install-rabbitmq install-mqtt install-kafka info build publish publish-test clean
+
+help: ## Danh sách lệnh
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
+
+# Makefile này chỉ là lối tắt cho `pym` khi làm việc TRONG repo. Người dùng thư
+# viện không có nó, nên mọi lệnh đều phải chạy được qua `pym` — và cách chắc
+# chắn nhất để giữ điều đó đúng là ở đây không tự viết gì cả, chỉ gọi lại.
+PYM := $(PY) -m pymodular.cli.main
+
+dev: ## Chạy API kèm autoreload
+	$(PYM) dev
+
+run: ## Chạy API chế độ production (nhiều worker — cần driver DB thật)
+	$(PYM) run --workers $(or $(WORKERS),4)
+
+module: ## Sinh khung module mới — dùng: make module name=alerts [entity=alert] [ws=1] [mq=1]
+	@test -n "$(name)" || { echo 'Thiếu tên. Dùng: make module name=alerts'; exit 1; }
+	$(PYM) module $(name) $(if $(entity),--entity $(entity),) $(if $(ws),--gateway,) $(if $(mq),--consumer,)
+
+gateway: ## Thêm gateway WebSocket vào module đã có — dùng: make gateway name=alerts
+	@test -n "$(name)" || { echo 'Thiếu tên. Dùng: make gateway name=alerts'; exit 1; }
+	$(PYM) module $(name) --gateway-only $(if $(entity),--entity $(entity),)
+
+consumer: ## Thêm consumer RabbitMQ vào module đã có — dùng: make consumer name=alerts
+	@test -n "$(name)" || { echo 'Thiếu tên. Dùng: make consumer name=alerts'; exit 1; }
+	$(PYM) module $(name) --consumer-only $(if $(entity),--entity $(entity),)
+
+migrate: ## Chạy migration lên bản mới nhất
+	$(PYM) migrate up
+
+migrate-create: ## Sinh migration từ thay đổi entity — dùng: make migrate-create m="them cot phone"
+	@test -n "$(m)" || { echo 'Thiếu tên. Dùng: make migrate-create m="mô tả thay đổi"'; exit 1; }
+	$(PYM) migrate create -m "$(m)"
+
+migrate-down: ## Lùi lại một bản
+	$(PYM) migrate down
+
+migrate-history: ## Lịch sử migration và bản đang áp dụng
+	@$(PYM) migrate history
+
+migrate-sql: ## In câu SQL thay vì chạy (để DBA duyệt trước)
+	$(PYM) migrate sql
+
+lint: ## Soi lỗi tĩnh
+	$(PYM) lint pymodular src tests
+
+lint-fix: ## Soi và tự sửa những lỗi sửa được
+	$(PYM) lint --fix pymodular src tests
+
+test: ## Chạy test
+	$(PYM) test
+
+install: ## Cài khung ở chế độ chỉnh sửa được (chưa có driver database)
+	$(PIP) install -e .
+
+install-dev: ## Cài kèm công cụ phát triển (pytest, httpx, ruff, build, twine)
+	$(PIP) install -e .
+	$(PYM) install dev
+	$(PIP) install build twine
+
+install-sqlite: ## Cài driver SQLite + ghi biến vào .env
+	$(PYM) install sqlite
+
+install-postgres: ## Cài driver PostgreSQL + ghi biến vào .env
+	$(PYM) install postgres
+
+install-mongo: ## Cài driver MongoDB + ghi biến vào .env
+	$(PYM) install mongodb
+
+install-redis: ## Cài Redis (cache, đếm, pub/sub) + ghi biến vào .env
+	$(PYM) install redis
+
+install-ws-redis: ## Bật adapter Redis cho WebSocket nhiều worker + ghi biến vào .env
+	$(PYM) install ws-redis
+
+install-rabbitmq: ## Cài client RabbitMQ + ghi biến vào .env
+	$(PYM) install rabbitmq
+
+install-mqtt: ## Cài client MQTT + ghi biến vào .env
+	$(PYM) install mqtt
+
+install-kafka: ## Cài client Kafka + ghi biến vào .env
+	$(PYM) install kafka
+
+
+
+
+
+
+
+info: ## Đang nối vào đâu, thư viện nào đã cài
+	@$(PYM) info
+
+build: ## Dựng wheel + sdist vào dist/
+	$(PYM) build
+
+publish-test: build ## Đẩy lên TestPyPI (thử trước khi đẩy thật)
+	$(PYM) publish --test
+
+publish: build ## Đẩy lên PyPI
+	$(PYM) publish
+
+clean: ## Xoá cache và bản dựng
+	$(PYM) clean

fastapi_modular-0.1.0/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.5
+Name: fastapi-modular
+Version: 0.1.0
+Summary: FastAPI theo kiến trúc module kiểu NestJS: DI container, controller dạng class, WebSocket, RabbitMQ/Redis/MQTT/Kafka
+Project-URL: Homepage, https://github.com/quanglinh2909/pymodular
+Project-URL: Documentation, https://github.com/quanglinh2909/pymodular/tree/main/docs
+Project-URL: Source, https://github.com/quanglinh2909/pymodular
+Project-URL: Issues, https://github.com/quanglinh2909/pymodular/issues
+Project-URL: Changelog, https://github.com/quanglinh2909/pymodular/blob/main/CHANGELOG.md
+Author-email: Oryza <developer@oryza.vn>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dependency-injection,fastapi,kafka,module,mqtt,nestjs,rabbitmq,redis,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi<1.0.0,>=0.115.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.6.0
+Requires-Dist: pydantic<3.0.0,>=2.9.0
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.32.0
+Provides-Extra: all
+Requires-Dist: aio-pika<10.0.0,>=9.4.0; extra == 'all'
+Requires-Dist: aiokafka<0.13.0,>=0.10.0; extra == 'all'
+Requires-Dist: aiomqtt<3.0.0,>=2.0.0; extra == 'all'
+Requires-Dist: aiosqlite>=0.20.0; extra == 'all'
+Requires-Dist: alembic>=1.13.0; extra == 'all'
+Requires-Dist: asyncpg>=0.29.0; extra == 'all'
+Requires-Dist: motor<4.0.0,>=3.6.0; extra == 'all'
+Requires-Dist: redis<7.0.0,>=5.0.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.30; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: kafka
+Requires-Dist: aiokafka<0.13.0,>=0.10.0; extra == 'kafka'
+Provides-Extra: mongodb
+Requires-Dist: motor<4.0.0,>=3.6.0; extra == 'mongodb'
+Provides-Extra: mqtt
+Requires-Dist: aiomqtt<3.0.0,>=2.0.0; extra == 'mqtt'
+Provides-Extra: postgres
+Requires-Dist: alembic>=1.13.0; extra == 'postgres'
+Requires-Dist: asyncpg>=0.29.0; extra == 'postgres'
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.30; extra == 'postgres'
+Provides-Extra: rabbitmq
+Requires-Dist: aio-pika<10.0.0,>=9.4.0; extra == 'rabbitmq'
+Provides-Extra: redis
+Requires-Dist: redis<7.0.0,>=5.0.0; extra == 'redis'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.20.0; extra == 'sqlite'
+Requires-Dist: alembic>=1.13.0; extra == 'sqlite'
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.30; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# pymodular
+
+FastAPI theo kiến trúc module kiểu NestJS: DI container, controller dạng class,
+repository chung cho nhiều loại database, gateway WebSocket có phòng, và bốn lớp
+hạ tầng tuỳ chọn: RabbitMQ, Redis, MQTT, Kafka.
+
+> **In English:** pymodular brings NestJS-style modular architecture to FastAPI —
+> a DI container, class-based controllers, auto-discovered modules, a shared
+> repository over four databases, a WebSocket gateway with rooms, and optional
+> RabbitMQ / Redis / MQTT / Kafka layers that stay dormant until enabled.
+> **Documentation is in Vietnamese**; the public API is English.
+
+## Bắt đầu
+
+Cần **Python 3.10+**.
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install fastapi-modular
+
+pym init          # đổ file vào THƯ MỤC HIỆN TẠI, không tạo thêm cấp
+pym dev
+```
+
+Mở http://localhost:8000/docs — đã có sẵn một module `health` chạy được.
+
+`pym init` lấy tên dự án theo **tên thư mục hiện tại**; đặt tên khác bằng
+`pym init --name ten-khac`. Nó không ghi đè file nào đã có, nên chạy được cả
+trong thư mục đang có sẵn code. Muốn nó tự tạo thư mục thì `pym new <tên>`.
+
+Lõi **không kéo theo** driver database hay client hàng đợi nào. Cần cái gì thì
+thêm cái đó:
+
+```bash
+pym install sqlite      # hoặc postgres, mongodb
+pym install rabbitmq    # hoặc redis, mqtt, kafka
+pym install all         # tất cả
+```
+
+`pym install` vừa cài thư viện vừa ghi biến vào `.env`. Muốn tự cài bằng pip
+cũng được: `pip install "fastapi-modular[sqlite,rabbitmq]"`.
+
+## Lệnh
+
+Một chương trình, hai tên: `pymodular` (đầy đủ) và `pym` (gõ tắt). Dưới đây dùng
+`pym` cho gọn.
+
+Tên lệnh rút gọn được tới khi nào tiền tố còn chỉ đúng một lệnh — `pym mo alerts`
+chạy y hệt `pym module alerts`. Nhập nhằng thì `pym` hỏi lại chứ không đoán:
+
+```
+$ pym m
+pym: lệnh 'm' chưa rõ — khớp với migrate, module. Gõ thêm vài chữ cho rõ.
+```
+
+| Lệnh | Rút gọn | Làm gì |
+|---|---|---|
+| `pym init [--name <tên>]` | `pym ini` | dựng dự án **trong thư mục hiện tại**, không ghi đè file nào đã có; tên dự án mặc định lấy theo tên thư mục |
+| `pym new <tên>` | `pym n` | dựng dự án trong một thư mục mới |
+| `pym dev` | `pym d` | chạy kèm autoreload |
+| `pym run --workers 4` | `pym r` | chạy chế độ production |
+| `pym module <tên>` | `pym mo` | sinh module: controller + service + dto + entity |
+| `pym module <tên> --gateway` | | kèm gateway WebSocket (`--consumer` cho RabbitMQ) |
+| `pym module <tên> --gateway-only` | | chỉ thêm gateway vào module **đã có** (`--consumer-only` cho RabbitMQ) |
+| `pym module <tên> --entity <Tên>` | | đặt tên lớp entity; mặc định đoán từ tên module |
+| `pym env <thành-phần>` | `pym e` | chỉ ghi biến cấu hình vào `.env` (không cài gì) |
+| `pym clean` | `pym c` | xoá cache và bản dựng (không đụng `data/`) |
+| `pym build` · `pym publish [--test]` | `pym b` · `pym p` | dựng wheel/sdist · đẩy lên PyPI |
+| `pym info` | `pym inf` | đang nối vào đâu, thư viện nào đã cài, cảnh báo cấu hình prod |
+| `pym migrate [up\|down\|history\|sql\|create]` | `pym mi` | Alembic |
+| `pym test` · `pym lint [--fix]` | `pym t` · `pym l` | pytest · ruff. `pym lint` không tham số soi `src`; truyền đường dẫn để soi chỗ khác |
+| **Thêm database** | | *cài thư viện **rồi** ghi biến vào `.env`* |
+| `pym install sqlite` | `pym ins s` | file `.db`, không cần server |
+| `pym install postgres` | `pym ins p` | PostgreSQL |
+| `pym install mongodb` | `pym ins mo` | MongoDB |
+| **Thêm hàng đợi** | | *cài thư viện **rồi** ghi biến vào `.env`* |
+| `pym install rabbitmq` | `pym ins ra` | hàng đợi bền, thử lại + DLQ |
+| `pym install redis` | `pym ins re` | cache, đếm nguyên tử, pub/sub |
+| `pym install mqtt` | `pym ins mq` | thiết bị IoT |
+| `pym install kafka` | `pym ins k` | nhật ký sự kiện đọc lại được |
+| `pym install ws-redis` | `pym ins w` | phát tin WebSocket xuyên nhiều worker |
+| `pym install dev` | `pym ins d` | pytest · pytest-asyncio · httpx · ruff — cần cho `pym test` / `pym lint` |
+| `pym install all` | `pym ins a` | tất cả những thứ trên, **trừ** `dev` |
+
+Tham số dạng danh sách cũng rút gọn theo cùng luật đó: `pym ins sq`,
+`pym e post`, `pym mi h`. Còn giá trị bạn tự đặt thì không bị đụng tới —
+`pym mo ins` tạo module tên đúng là `ins`.
+
+Host và cổng lấy từ `APP_HOST` / `APP_PORT` trong `.env`, nên `pym dev` không cần
+tham số. `pym --help` cho danh sách đầy đủ.
+
+## Thêm module
+
+```bash
+pym module alerts              # controller + service + dto + entities
+pym module alerts --gateway    # kèm gateway WebSocket
+pym module alerts --consumer   # kèm consumer RabbitMQ
+```
+
+Route xuất hiện ngay, bảng được tạo ngay, validate chạy ngay — chỉ thân hàm là
+chưa viết (gọi vào trả 501 kèm tên hàm). Việc của bạn: thêm trường vào entity và
+DTO, rồi viết thân hàm trong service.
+
+Không phải sửa file nào khác. Chi tiết: [docs/architecture.md](docs/architecture.md#thêm-module-mới).
+
+## Chọn database
+
+`pym install sqlite` (hoặc `postgres`, `mongodb`) làm cả hai việc: cài thư viện
+của đúng driver đó, rồi ghi biến vào `.env`. Chỉ muốn ghi `.env` mà không cài gì
+thì dùng `pym env sqlite`.
+
+`pym env` ghi mỗi biến kèm giải thích, cho biết nó **bắt buộc hay tuỳ chọn** và
+**mặc định là gì** nếu xoá dòng đi. `pym info` cho biết hiện đang nối vào đâu.
+
+Chi tiết: [docs/database.md](docs/database.md).
+
+## Cấu hình của riêng bạn
+
+Kế thừa `Settings` là thêm được biến vào `.env`, không phải sửa gì trong khung:
+
+```python
+# src/core/config.py — pym init sinh sẵn file này
+class AppSettings(Settings):
+    team_name: str = Field(default="", alias="APP_TEAM_NAME")
+    jwt: JwtSettings = Field(default_factory=JwtSettings, alias="APP_JWT")   # -> APP_JWT__SECRET
+```
+
+Service nhận `AppSettings` qua DI với gợi ý kiểu đầy đủ.
+Chi tiết: [docs/config.md](docs/config.md).
+
+## Điểm vào là file của bạn
+
+`pym init` sinh ra `src/main.py` với từng bước lắp ráp bày ra hết — thêm
+middleware, đổi CORS, gắn router bên thứ ba thì sửa thẳng ở đó:
+
+```python
+settings = bind_settings(AppSettings())
+configure_logging(settings.log)
+
+app = new_fastapi(settings, lifespan=lifespan)
+add_middleware(app, settings)                       # CORS + request-id + access log
+register_error_handlers(app, debug=settings.debug)
+register_routes(app, prefix=settings.api_prefix)    # quét src/api/
+```
+
+Chưa cần sửa gì thì cả khối rút lại còn `app = create_app(AppSettings())` —
+`create_app` chạy đúng dãy trên, không hơn.
+
+Vòng đời cũng vậy: `src/core/lifespan.py` là của bạn, chỉ **bọc** phần hạ tầng
+của khung lại:
+
+```python
+@asynccontextmanager
+async def lifespan(app):
+    async with framework_lifespan(app):   # khung mở database, hàng đợi
+        await warm_cache()                # việc riêng — database đã dùng được
+        try:
+            yield
+        finally:
+            await flush_ledger()          # việc riêng — database VẪN CÒN
+```
+
+Đo trên log thật: `db.connected` → `app.started` → **`app.ready`** → …phục vụ… →
+**`app.closing`** → `app.stopping` → `app.stopped`.
+
+## Realtime (WebSocket)
+
+Một client một kết nối, vào phòng để nhận tin theo nhóm, hoặc nhận tin gửi
+thẳng cho riêng mình:
+
+```python
+@gateway(path="/ws/alerts", guards=[WsJwt], client_rooms=True)
+class AlertGateway:
+    @subscribe("alert.ack")
+    async def ack(self, socket: Socket, payload: AlertAck) -> dict:
+        return {"ok": True}
+```
+
+```bash
+pym dev
+# ws://localhost:8000/ws/chat?client_id=an
+
+pym module alerts --gateway-only   # thêm gateway vào module đã có
+pym install ws-redis               # bắt buộc khi chạy nhiều worker
+```
+
+Đẩy tin từ REST hay tác vụ nền: nhận `WebSocketServer` qua `__init__` rồi gọi
+`to_room` / `to_user` / `to_socket`.
+
+Hướng dẫn đầy đủ (kèm cách dùng bằng **Postman** và client **Next.js**):
+[docs/websocket.md](docs/websocket.md).
+
+## Hàng đợi (RabbitMQ — tuỳ chọn)
+
+```python
+await self._mq.publish("events", "alert.created.hanoi", {"id": "A1"})
+
+# Mặc định: đúng MỘT hàng đợi trên broker, hỏng là bỏ (có log).
+@rabbitmq_subscriber("events", "alert.created", queue="alert-mailer")
+async def gui_mail(self, payload: AlertCreated) -> None: ...
+
+# Tự bật khi tin đáng tiền -> thêm alert-mailer.retry và alert-mailer.dlq
+@rabbitmq_subscriber("events", "alert.created", queue="alert-mailer",
+                     max_retries=3, dead_letter=True)
+async def gui_mail(self, payload: AlertCreated) -> None: ...
+```
+
+```bash
+pym install rabbitmq            # cài aio-pika + ghi APP_RABBITMQ__* vào .env
+pym module alerts --consumer    # module mới kèm consumer
+```
+
+Không cài, không bật thì mọi thứ chạy y như chưa từng có nó. Broker rớt thì app
+vẫn phục vụ và tự nối lại. Chi tiết: [docs/rabbitmq.md](docs/rabbitmq.md).
+
+## Redis, MQTT, Kafka (cũng tuỳ chọn)
+
+Cùng một khuôn với RabbitMQ: một package riêng dưới `infrastructure/`, một nhóm
+biến `APP_<TÊN>__*`, mặc định **tắt**, thư viện chỉ import khi bật, và luôn tự
+nối lại.
+
+```bash
+pym install redis    # cache, đếm, pub/sub      -> docs/redis.md
+pym install mqtt     # thiết bị IoT             -> docs/mqtt.md
+pym install kafka    # nhật ký sự kiện          -> docs/kafka.md
+```
+
+```python
+await redis.cached("bao-cao:A", tinh_that, ttl=30)     # trượt thì tính, trúng thì thôi
+await mqtt.publish("thiet-bi/bep/den", "ON", qos=1, retain=True)
+await kafka.publish("don-hang", don, key=don.ma_don)   # cùng key = cùng thứ tự
+
+@redis_subscriber("gia:*")                      # Redis: mọi worker một bản sao
+@mqtt_subscriber("thiet-bi/+/nhiet-do", qos=1)  # MQTT:  + một tầng, # mọi tầng
+@kafka_subscriber("don-hang", group="kho-van")  # Kafka: mỗi nhóm một con trỏ đọc
+```
+
+| Cần gì | Dùng gì |
+|---|---|
+| tin không được mất, chia việc cho worker | RabbitMQ |
+| nhanh, mọi worker nhận một bản sao, mất vài tin cũng được | Redis |
+| thiết bị, mạng chập chờn, kết nối lâu | MQTT |
+| đọc lại được lịch sử, nhiều nhóm đọc độc lập | Kafka |
+
+## Vận hành
+
+```bash
+curl localhost:8000/api/health        # liveness
+curl localhost:8000/api/health/ready  # readiness, có ping database
+curl localhost:8000/api/metrics       # số đo dạng Prometheus
+pym migrate                           # chạy migration (SQL)
+pym info                              # cấu hình đang dùng + cảnh báo prod
+```
+
+Chi tiết: [docs/operations.md](docs/operations.md).
+
+## Cấu trúc repo này
+
+```
+pymodular/          THƯ VIỆN — thứ được đóng gói và cài về
+  core/             DI, controller, config, WebSocket, guard, số đo
+  infrastructure/   database, rabbitmq, redis, mqtt, kafka (mỗi thứ một package)
+  cli/              init · new · module · dev · run · install · env · info
+                    migrate · test · lint · clean · build · publish
+  factory.py        create_app()
+  discovery.py      tự quét package ứng dụng, dựng router
+src/                ỨNG DỤNG MẪU — không nằm trong gói cài; xoá thoải mái
+  main.py           điểm vào: lắp ráp app — file của bạn, không phải của khung
+  core/config.py    AppSettings: kế thừa Settings để thêm biến .env của bạn
+  core/lifespan.py  việc lúc khởi động / lúc tắt của riêng ứng dụng
+  api/              các module nghiệp vụ; mỗi thư mục con là một module
+tests/              341 test chạy không cần hạ tầng, 40 test nữa bật khi có server thật
+docs/               tài liệu tra cứu
+```
+
+`pymodular/` không import gì từ `src/`. Nó chỉ biết "có một package tên
+`src.api`, quét nó đi" — nên dự án xếp khác cũng được, khai một lần trong
+`src/main.py`: `register_routes(app, package="cong_ty.dich_vu")`.
+
+## Đóng góp
+
+```bash
+git clone <repo> && cd pymodular
+pip install -e ".[all,dev]"
+pym dev                        # chạy ứng dụng mẫu trong src/
+pym test
+pym lint pymodular src tests
+```
+
+Nhóm test cần hạ tầng thật chỉ chạy khi có biến môi trường tương ứng:
+
+```bash
+docker run -d -p 6379:6379 redis:7-alpine
+TEST_REDIS_URL=redis://localhost:6379/0 pym test
+```
+
+Xem đầu mỗi file `tests/test_<tên>.py` để biết lệnh Docker và biến cần đặt.
+
+## Giấy phép
+
+MIT — xem [LICENSE](LICENSE).
+
+## Tài liệu
+
+- [docs/architecture.md](docs/architecture.md) — cấu trúc module, DI, đối chiếu NestJS
+- [docs/config.md](docs/config.md) — Settings, thứ tự ưu tiên, thêm biến của riêng bạn
+- [docs/database.md](docs/database.md) — memory / SQLite / PostgreSQL / MongoDB
+- [docs/migrations.md](docs/migrations.md) — Alembic: sinh, chạy, lùi migration
+- [docs/websocket.md](docs/websocket.md) — gateway WebSocket, phòng, Postman, Next.js
+- [docs/rabbitmq.md](docs/rabbitmq.md) — exchange, topic, consumer nền, `.retry` / `.dlq`
+- [docs/redis.md](docs/redis.md) — cache, đếm nguyên tử, pub/sub
+- [docs/mqtt.md](docs/mqtt.md) — QoS, retain, luật khớp topic `+` và `#`
+- [docs/kafka.md](docs/kafka.md) — nhóm consumer, phân vùng, `.dlt`
+- [docs/operations.md](docs/operations.md) — guard, circuit breaker, metrics, trace