xime 0.1.0__tar.gz

xime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nguyễn Hữu Thắng
+
+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.

xime-0.1.0/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: xime
+Version: 0.1.0
+Summary: Spring Boot-inspired dependency injection and convention framework for Python backends
+Project-URL: Homepage, https://github.com/nguyen-huu-thang/xime-framework
+Project-URL: Repository, https://github.com/nguyen-huu-thang/xime-framework
+Project-URL: Issues, https://github.com/nguyen-huu-thang/xime-framework/issues
+Author-email: Nguyễn Hữu Thắng <nguyen-huu-thang@outlook.com>
+License: MIT License
+        
+        Copyright (c) 2025 Nguyễn Hữu Thắng
+        
+        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.
+License-File: LICENSE
+Keywords: backend,convention,dependency-injection,fastapi,framework,spring-boot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.11
+Requires-Dist: dependency-injector>=4.41.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: apscheduler>=4.0; extra == 'all'
+Requires-Dist: grpcio-tools>=1.60; extra == 'all'
+Requires-Dist: grpcio>=1.60; extra == 'all'
+Requires-Dist: msgpack>=1.0; extra == 'all'
+Requires-Dist: protobuf>=4.25; extra == 'all'
+Requires-Dist: pyjwt>=2.8; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: anyio>=4.0; extra == 'dev'
+Requires-Dist: apscheduler>=4.0; extra == 'dev'
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: grpcio>=1.60; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: msgpack>=1.0; extra == 'dev'
+Requires-Dist: protobuf>=4.25; extra == 'dev'
+Requires-Dist: pyjwt>=2.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'dev'
+Provides-Extra: grpc
+Requires-Dist: grpcio-tools>=1.60; extra == 'grpc'
+Requires-Dist: grpcio>=1.60; extra == 'grpc'
+Requires-Dist: protobuf>=4.25; extra == 'grpc'
+Provides-Extra: jwt
+Requires-Dist: pyjwt>=2.8; extra == 'jwt'
+Provides-Extra: scheduler
+Requires-Dist: apscheduler>=4.0; extra == 'scheduler'
+Provides-Extra: socket
+Requires-Dist: msgpack>=1.0; extra == 'socket'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'sqlalchemy'
+Provides-Extra: web
+Requires-Dist: uvicorn[standard]>=0.27; extra == 'web'
+Description-Content-Type: text/markdown
+
+# XIME Framework
+
+**English** | [Tiếng Việt](README-vn.md)
+
+> A Python backend framework inspired by Spring Boot's conventions — built to respect Python's philosophy.
+
+---
+
+XIME is not another HTTP framework. Taking inspiration from Spring Boot's convention-over-configuration approach, it sits **on top of** FastAPI, SQLAlchemy, and gRPC — providing a convention engine, automatic dependency injection, and architectural guardrails so you can focus on business logic instead of wiring.
+
+```python
+# Before XIME — wire everything manually
+container.user_service = providers.Singleton(
+    UserService,
+    repository=container.user_repository,
+    transaction=container.transaction_manager,
+)
+
+# With XIME — just write your class
+class UserService:
+    def __init__(
+        self,
+        repository: UserRepository,
+        transaction: TransactionManager,
+    ):
+        self.repository = repository
+        self.transaction = transaction
+```
+
+XIME reads your type hints, scans your packages, builds the dependency graph, validates it at startup, and wires everything together — automatically.
+
+---
+
+## Why XIME?
+
+Python has excellent libraries for HTTP, databases, and serialization. What it lacks is a **convention layer** that:
+
+- Automatically discovers and wires dependencies from constructor type hints
+- Enforces architectural boundaries through directory structure
+- Validates the dependency graph at startup — not at runtime when a user hits an endpoint
+- Provides a consistent structure for Clean Architecture / DDD / Modular Monolith projects
+
+XIME fills that gap. It does not replace FastAPI or SQLAlchemy — it makes them easier to use at scale.
+
+---
+
+## How It Works
+
+```text
+Application Code
+      ↓
+   XIME Core          ← scanning, DI, lifecycle, config
+      ↓
+Dependency Injector   ← runtime DI engine
+      ↓
+Python Objects
+```
+
+XIME's startup pipeline:
+
+1. Load framework configuration (`config/dependency.py`)
+2. Load runtime configuration (`resources/application.yml`)
+3. Scan declared packages
+4. Resolve type hints
+5. Build dependency graph
+6. **Validate graph** — detect cycles, missing implementations, ambiguous bindings
+7. Create singletons
+8. Start adapters (FastAPI, gRPC, ...)
+
+If anything is wrong, the app **fails immediately at startup** with a clear error — not later in production.
+
+---
+
+## Installation
+
+```bash
+pip install xime
+```
+
+Optional starters:
+
+```bash
+pip install xime[web]        # uvicorn (ASGI server)
+pip install xime[sqlalchemy] # async SQLAlchemy
+pip install xime[jwt]        # JWT auth
+pip install xime[scheduler]  # cron-style tasks
+pip install xime[grpc]       # gRPC adapter
+pip install xime[all]        # everything above
+```
+
+---
+
+## Quick Start
+
+```python
+# app/main.py — REST only
+from xime import Application
+from xime.adapters.web import WebAdapter
+
+app = Application()
+app.use(WebAdapter())
+app.run()
+```
+
+```python
+# app/main.py — REST + gRPC simultaneously
+from xime import Application
+from xime.adapters.web import WebAdapter
+from xime.adapters.grpc import GrpcAdapter
+
+app = Application()
+app.use(WebAdapter())
+app.use(GrpcAdapter())
+app.run()
+```
+
+```python
+# app/main.py — Multiple servers (public API + internal admin)
+from xime import Application
+from xime.adapters.web import WebAdapter
+
+app = Application()
+app.use(WebAdapter())                              # server_id="default", port from application.yml
+app.use(WebAdapter("admin", "127.0.0.1", 8081))   # server_id="admin", explicit host/port
+app.run()
+```
+
+```python
+# app/config/dependency.py
+from xime import BindingConfig
+
+dependency = BindingConfig()
+dependency.scan("application.usecase", "infrastructure.repository")
+dependency.bind({UserRepository: JpaUserRepository})
+```
+
+```python
+# app/api/rest/user_controller.py
+from xime.adapters.web.routing import get, post
+
+class UserController:
+    prefix = "/users"
+
+    def __init__(self, use_case: GetUserUseCase) -> None:
+        self._use_case = use_case
+
+    @get("/{user_id}", response_model=UserResponse)
+    async def get_user(self, user_id: int) -> UserResponse:
+        return await self._use_case.execute(user_id)
+```
+
+```python
+# app/main.py
+from xime import Application
+from xime.adapters.web import WebAdapter
+
+app = Application()
+app.use(WebAdapter())
+app.run()
+```
+
+```bash
+python app/main.py
+```
+
+---
+
+## Features
+
+| Feature | Description |
+| --- | --- |
+| **Constructor Injection** | Declare dependencies as constructor params — XIME wires them |
+| **Directory-Driven DI** | Package location determines component role — no annotations |
+| **Interface Binding** | Explicit `Protocol` → implementation mapping, validated at startup |
+| **Fail Fast** | Circular deps, missing implementations, ambiguous bindings → startup error |
+| **Lifecycle Hooks** | `PostConstruct`, `PreDestroy` for managed startup/shutdown |
+| **Initialization Order** | `dependency.order([A, B, C])` — control `post_construct()` execution order across independent classes |
+| **Multi-Server** | Multiple `WebAdapter` / `GrpcAdapter` / `SocketAdapter` per process, each with its own `server_id` |
+| **Event Bus** | Internal pub/sub for decoupled domain events |
+| **Request Context** | Per-request data via `ContextVar`, set by adapters |
+| **Security Context** | `AuthenticationManager`, `AuthorizationManager` in core |
+| **Two-Layer Config** | Framework config (Python) + Runtime config (YAML) |
+| **Transaction API** | Explicit `async with self.transaction():` — no hidden AOP |
+| **Class-Based Controllers** | Controllers are DI singletons, methods map to routes |
+| **Code-First gRPC** | Write Python DTOs, XIME generates `.proto` + stubs; field-number stability via lock file |
+| **Socket Adapter** | Unix Domain Socket IPC for same-host Native Engine calls (Linux); `@command` / `@stream` |
+
+---
+
+## Starters
+
+Optional modules, similar to `spring-boot-starter-*`:
+
+| Starter | What it provides | Status |
+| --- | --- | --- |
+| `xime.starters.sqlalchemy` | Async DB session, `SqlAlchemyTransactionManager` | ✅ Implemented |
+| `xime.starters.jwt` | JWT signing, verification, middleware | ✅ Implemented |
+| `xime.starters.scheduler` | Cron-style task scheduling | ✅ Implemented |
+| `xime.starters.redis` | Redis client integration | 🔲 Planned |
+| `xime.starters.cache` | Cache abstraction layer | 🔲 Planned |
+
+---
+
+## Design Principles
+
+- **Explicit over implicit** — binding, routing, config are always declared, never auto-discovered by magic
+- **Constructor injection only** — no `@inject`, no field injection, no `@autowired`
+- **No annotations for roles** — `@service`, `@repository`, `@component` do not exist; directory determines role
+- **Fail fast** — errors surface at startup, not at runtime
+- **Thin wrapper** — XIME does not rewrite FastAPI, SQLAlchemy, or gRPC; it orchestrates them
+
+---
+
+## Project Status
+
+XIME is in **active development** (v0.1.0 — Alpha). The following are implemented: core DI, lifecycle, event bus, security context, configuration, JWT starter, scheduler starter, SQLAlchemy starter, Web adapter (FastAPI + routing), gRPC adapter (proto-first + **code-first**), **Socket adapter** (Unix Domain Socket IPC), multi-server support, and initialization order (`dependency.order()`). WebSocket support is partial. Redis and Cache starters are planned.
+
+---
+
+## Contributing
+
+XIME is a solo project that needs community help to grow. There is still ground to cover: completing WebSocket support, Redis/Cache starters, CLI scaffolding, testing utilities, and more.
+
+**Ways to contribute:**
+
+- Read the [architecture docs](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/architecture.md) to understand the design
+- Pick an open area from the [roadmap](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/contributing.md#roadmap)
+- Open an issue to discuss a feature or bug
+- Submit a pull request
+
+Please read [CONTRIBUTING](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/contributing.md) before opening a PR.
+
+---
+
+## Documentation
+
+| Document | Description |
+| --- | --- |
+| [Getting Started](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/getting-started.md) | First app in 5 minutes |
+| [Architecture](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/architecture.md) | How XIME is structured internally |
+| [Core Concepts](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/core-concepts.md) | DI, interface binding, scopes |
+| [Configuration](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/configuration.md) | Framework config + runtime YAML |
+| [Routing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/routing.md) | Class-based controllers, route decorators |
+| [Transaction](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/transaction.md) | Explicit transaction management |
+| [Code-First gRPC](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/grpc-codefirst.md) | Generate `.proto` from Python DTOs; field-number stability; `xime grpc generate/check` |
+| [Socket Adapter](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/socket-adapter.md) | Unix Domain Socket IPC for same-host Native Engine calls |
+| [Starters](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/starters.md) | SQLAlchemy, JWT, Scheduler |
+| [Testing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/testing.md) | DI overrides, fakes, test utilities |
+| [Contributing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/contributing.md) | How to contribute, roadmap |
+
+---
+
+## License
+
+MIT

xime-0.1.0/README-vn.md

@@ -0,0 +1,245 @@
+# XIME Framework
+
+[English](README.md) | **Tiếng Việt**
+
+> Framework backend Python lấy cảm hứng từ Spring Boot — nhưng được xây dựng theo triết lý Python.
+
+---
+
+XIME không phải một HTTP framework khác. Lấy cảm hứng từ triết lý convention-over-configuration của Spring Boot, nó nằm **phía trên** FastAPI, SQLAlchemy và gRPC — cung cấp convention engine, dependency injection tự động và các guardrail kiến trúc để bạn tập trung vào nghiệp vụ thay vì dây nhợ cấu hình.
+
+```python
+# Trước XIME — tự kết nối mọi thứ thủ công
+container.user_service = providers.Singleton(
+    UserService,
+    repository=container.user_repository,
+    transaction=container.transaction_manager,
+)
+
+# Với XIME — chỉ cần viết class
+class UserService:
+    def __init__(
+        self,
+        repository: UserRepository,
+        transaction: TransactionManager,
+    ):
+        self.repository = repository
+        self.transaction = transaction
+```
+
+XIME đọc type hint, quét package, xây dựng dependency graph, validate tại startup và kết nối mọi thứ — tự động.
+
+---
+
+## Tại sao cần XIME?
+
+Python có các thư viện xuất sắc cho HTTP, database và serialization. Điều còn thiếu là một **tầng convention** có thể:
+
+- Tự động phát hiện và kết nối dependency từ type hint của constructor
+- Áp dụng ranh giới kiến trúc thông qua cấu trúc thư mục
+- Validate dependency graph lúc startup — không phải lúc runtime khi user gọi endpoint
+- Cung cấp cấu trúc nhất quán cho các project theo Clean Architecture / DDD / Modular Monolith
+
+XIME lấp đầy khoảng trống đó. Nó không thay thế FastAPI hay SQLAlchemy — nó giúp chúng dễ dùng hơn ở quy mô lớn.
+
+---
+
+## Cách hoạt động
+
+```text
+Application Code
+      ↓
+   XIME Core          ← scanning, DI, lifecycle, config
+      ↓
+Dependency Injector   ← DI engine runtime
+      ↓
+Python Objects
+```
+
+Trình tự khởi động của XIME:
+
+1. Nạp framework configuration (`config/dependency.py`)
+2. Nạp runtime configuration (`resources/application.yml`)
+3. Quét các package được khai báo
+4. Phân giải type hint
+5. Xây dựng dependency graph
+6. **Validate graph** — phát hiện vòng lặp, thiếu implementation, binding mơ hồ
+7. Tạo singleton
+8. Khởi động adapter (FastAPI, gRPC, ...)
+
+Nếu có vấn đề, app **thất bại ngay lúc startup** với thông báo rõ ràng — không phải sau đó trên production.
+
+---
+
+## Cài đặt
+
+```bash
+pip install xime
+```
+
+Starters tùy chọn:
+
+```bash
+pip install xime[web]        # uvicorn (ASGI server)
+pip install xime[sqlalchemy] # async SQLAlchemy
+pip install xime[jwt]        # xác thực JWT
+pip install xime[scheduler]  # lập lịch tác vụ kiểu cron
+pip install xime[grpc]       # gRPC adapter
+pip install xime[all]        # tất cả ở trên
+```
+
+---
+
+## Bắt đầu nhanh
+
+```python
+# app/main.py — REST only
+from xime import Application
+from xime.adapters.web import WebAdapter
+
+app = Application()
+app.use(WebAdapter())
+app.run()
+```
+
+```python
+# app/main.py — REST + gRPC đồng thời
+from xime import Application
+from xime.adapters.web import WebAdapter
+from xime.adapters.grpc import GrpcAdapter
+
+app = Application()
+app.use(WebAdapter())
+app.use(GrpcAdapter())
+app.run()
+```
+
+```python
+# app/main.py — Nhiều server (public API + internal admin)
+from xime import Application
+from xime.adapters.web import WebAdapter
+
+app = Application()
+app.use(WebAdapter())                              # server_id="default", port từ application.yml
+app.use(WebAdapter("admin", "127.0.0.1", 8081))   # server_id="admin", host/port tường minh
+app.run()
+```
+
+```python
+# app/config/dependency.py
+from xime import BindingConfig
+
+dependency = BindingConfig()
+dependency.scan("application.usecase", "infrastructure.repository")
+dependency.bind({UserRepository: JpaUserRepository})
+```
+
+```python
+# app/api/rest/user_controller.py
+from xime.adapters.web.routing import get, post
+
+class UserController:
+    prefix = "/users"
+
+    def __init__(self, use_case: GetUserUseCase) -> None:
+        self._use_case = use_case
+
+    @get("/{user_id}", response_model=UserResponse)
+    async def get_user(self, user_id: int) -> UserResponse:
+        return await self._use_case.execute(user_id)
+```
+
+```bash
+python app/main.py
+```
+
+---
+
+## Tính năng
+
+| Tính năng | Mô tả |
+| --- | --- |
+| **Constructor Injection** | Khai báo dependency qua tham số constructor — XIME tự kết nối |
+| **Directory-Driven DI** | Vị trí package quyết định vai trò component — không annotation |
+| **Interface Binding** | Ánh xạ `Protocol` → implementation tường minh, validate lúc startup |
+| **Fail Fast** | Vòng lặp, thiếu implementation, binding mơ hồ → lỗi startup |
+| **Lifecycle Hooks** | `PostConstruct`, `PreDestroy` cho startup/shutdown được quản lý |
+| **Thứ tự khởi tạo** | `dependency.order([A, B, C])` — kiểm soát thứ tự chạy `post_construct()` giữa các class độc lập |
+| **Multi-Server** | Nhiều `WebAdapter` / `GrpcAdapter` / `SocketAdapter` cùng tiến trình, mỗi cái có `server_id` riêng |
+| **Event Bus** | Pub/sub nội bộ cho domain event |
+| **Request Context** | Dữ liệu theo request qua `ContextVar`, được thiết lập bởi adapter |
+| **Security Context** | `AuthenticationManager`, `AuthorizationManager` trong core |
+| **Two-Layer Config** | Framework config (Python) + Runtime config (YAML) |
+| **Transaction API** | `async with self.transaction():` tường minh — không có AOP ẩn |
+| **Class-Based Controllers** | Controller là DI singleton, method ánh xạ thành route |
+| **Code-First gRPC** | Viết Python DTO, XIME sinh `.proto` + stub; ổn định field number qua lock file |
+| **Socket Adapter** | IPC qua Unix Domain Socket cho Native Engine cùng máy (Linux); `@command` / `@stream` |
+
+---
+
+## Starters
+
+Module tùy chọn, tương tự `spring-boot-starter-*`:
+
+| Starter | Cung cấp gì | Trạng thái |
+| --- | --- | --- |
+| `xime.starters.sqlalchemy` | Async DB session, `SqlAlchemyTransactionManager` | ✅ Đã implement |
+| `xime.starters.jwt` | JWT signing, verification, middleware | ✅ Đã implement |
+| `xime.starters.scheduler` | Lập lịch tác vụ kiểu cron | ✅ Đã implement |
+| `xime.starters.redis` | Tích hợp Redis client | 🔲 Đang kế hoạch |
+| `xime.starters.cache` | Abstraction layer cho caching | 🔲 Đang kế hoạch |
+
+---
+
+## Nguyên tắc thiết kế
+
+- **Explicit hơn implicit** — binding, routing, config luôn được khai báo tường minh, không tự động phát hiện bằng magic
+- **Chỉ constructor injection** — không có `@inject`, field injection, hay `@autowired`
+- **Không annotation cho vai trò** — `@service`, `@repository`, `@component` không tồn tại; thư mục quyết định vai trò
+- **Fail fast** — lỗi xuất hiện lúc startup, không phải lúc runtime
+- **Wrapper mỏng** — XIME không viết lại FastAPI, SQLAlchemy hay gRPC; nó điều phối chúng
+
+---
+
+## Trạng thái dự án
+
+XIME đang trong **giai đoạn phát triển tích cực** (v0.1.0 — Alpha). Đã implement: core DI, lifecycle, event bus, security context, configuration, JWT starter, scheduler starter, SQLAlchemy starter, Web adapter (FastAPI + routing), gRPC adapter (proto-first + **code-first**), **Socket adapter** (Unix Domain Socket IPC), multi-server support và thứ tự khởi tạo (`dependency.order()`). WebSocket đang hoàn thiện. Redis và Cache starter đang được kế hoạch.
+
+---
+
+## Đóng góp
+
+XIME là dự án cá nhân cần sự giúp đỡ của cộng đồng để phát triển. Còn việc cần làm: hoàn thiện WebSocket, Redis/Cache starter, CLI scaffolding, testing utilities và nhiều hơn nữa.
+
+**Cách đóng góp:**
+
+- Đọc [tài liệu kiến trúc](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/architecture.md) để hiểu thiết kế
+- Chọn một mảng từ [roadmap](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/contributing.md#roadmap)
+- Mở issue để thảo luận tính năng hoặc bug
+- Gửi pull request
+
+Vui lòng đọc [CONTRIBUTING](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/contributing.md) trước khi mở PR.
+
+---
+
+## Tài liệu
+
+| Tài liệu | Mô tả |
+| --- | --- |
+| [Bắt đầu nhanh](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/getting-started.md) | App đầu tiên trong 5 phút |
+| [Kiến trúc](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/architecture.md) | Cấu trúc nội bộ của XIME |
+| [Khái niệm cốt lõi](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/core-concepts.md) | DI, interface binding, scope |
+| [Cấu hình](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/configuration.md) | Framework config + runtime YAML |
+| [Routing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/routing.md) | Class-based controller, route decorator |
+| [Transaction](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/transaction.md) | Quản lý transaction tường minh |
+| [Code-First gRPC](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/grpc-codefirst.md) | Sinh `.proto` từ Python DTO; ổn định field number; `xime grpc generate/check` |
+| [Socket Adapter](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/socket-adapter.md) | IPC qua Unix Domain Socket cho Native Engine cùng máy |
+| [Starters](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/starters.md) | SQLAlchemy, JWT, Scheduler |
+| [Testing](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/testing.md) | DI override, fake, test utilities |
+| [Đóng góp](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/vn/contributing.md) | Cách đóng góp, roadmap |
+
+---
+
+## Giấy phép
+
+MIT