Metadata-Version: 2.5
Name: xime
Version: 0.8.2
Summary: A Python backend framework with a built-in DI container: HTTP, WebSocket, gRPC, sockets, MQTT, Modbus TCP and OPC UA from one application, scaled across processes with no external process manager.
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-Expression: MIT
License-File: LICENSE
Keywords: asyncio,backend,dependency-injection,fastapi,framework,grpc,iot,microservices,modbus,mqtt,multiprocessing,opc-ua,websocket
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Manufacturing
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.133.0
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: starlette>=1.3.1
Provides-Extra: all
Requires-Dist: aioboto3>=12; extra == 'all'
Requires-Dist: aiomqtt>=2.1.0; extra == 'all'
Requires-Dist: aiosmtplib>=5.1.1; extra == 'all'
Requires-Dist: apscheduler>=4.0.0a6; extra == 'all'
Requires-Dist: asyncua>=2.0; extra == 'all'
Requires-Dist: botocore; extra == 'all'
Requires-Dist: grpcio-tools>=1.60; extra == 'all'
Requires-Dist: grpcio>=1.60; extra == 'all'
Requires-Dist: lmdb>=1.7.5; extra == 'all'
Requires-Dist: msgpack>=1.2.1; extra == 'all'
Requires-Dist: paho-mqtt>=2.1; extra == 'all'
Requires-Dist: protobuf>=6.33.5; extra == 'all'
Requires-Dist: pyjwt>=2.13; extra == 'all'
Requires-Dist: pymodbus>=3.14; extra == 'all'
Requires-Dist: python-multipart>=0.0.31; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]>=2.0.38; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'all'
Provides-Extra: dev
Requires-Dist: aioboto3>=12; extra == 'dev'
Requires-Dist: aiomqtt>=2.1.0; extra == 'dev'
Requires-Dist: aiosmtplib>=5.1.1; extra == 'dev'
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: anyio>=4.0; extra == 'dev'
Requires-Dist: apscheduler>=4.0.0a6; extra == 'dev'
Requires-Dist: asyncpg>=0.29; extra == 'dev'
Requires-Dist: asyncua>=2.0; extra == 'dev'
Requires-Dist: botocore; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: cryptography>=50.0.0; 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: lmdb>=1.7.5; extra == 'dev'
Requires-Dist: msgpack>=1.2.1; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: paho-mqtt>=2.1; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: protobuf>=6.33.5; extra == 'dev'
Requires-Dist: pyjwt>=2.13; extra == 'dev'
Requires-Dist: pymodbus>=3.14; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: python-multipart>=0.0.31; extra == 'dev'
Requires-Dist: redis>=5.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: sqlalchemy[asyncio]>=2.0.38; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: types-aiobotocore-s3>=3.9; 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>=6.33.5; extra == 'grpc'
Provides-Extra: jwt
Requires-Dist: pyjwt>=2.13; extra == 'jwt'
Provides-Extra: lmdb
Requires-Dist: lmdb>=1.7.5; extra == 'lmdb'
Provides-Extra: mail
Requires-Dist: aiosmtplib>=5.1.1; extra == 'mail'
Provides-Extra: modbus
Requires-Dist: pymodbus>=3.14; extra == 'modbus'
Provides-Extra: mqtt
Requires-Dist: aiomqtt>=2.1.0; extra == 'mqtt'
Requires-Dist: paho-mqtt>=2.1; extra == 'mqtt'
Provides-Extra: opcua
Requires-Dist: asyncua>=2.0; extra == 'opcua'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Provides-Extra: s3
Requires-Dist: aioboto3>=12; extra == 's3'
Requires-Dist: botocore; extra == 's3'
Provides-Extra: scheduler
Requires-Dist: apscheduler>=4.0.0a6; extra == 'scheduler'
Provides-Extra: socket
Requires-Dist: msgpack>=1.2.1; extra == 'socket'
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy[asyncio]>=2.0.38; extra == 'sqlalchemy'
Provides-Extra: web
Requires-Dist: python-multipart>=0.0.31; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'web'
Description-Content-Type: text/markdown

<div align="center">

# XIME Framework

**One DI container for devices, services and people.**

[![PyPI version](https://img.shields.io/pypi/v/xime.svg)](https://pypi.org/project/xime/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://pypi.org/project/xime/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nguyen-huu-thang/xime-framework/blob/main/LICENSE)

**English** | [Tiếng Việt](https://github.com/nguyen-huu-thang/xime-framework/blob/main/README-vn.md)

[Documentation](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/getting-started.md) · [Examples](#-example-projects)

</div>

---

XIME is a convention layer for Python microservices. It sits **on top of** FastAPI, SQLAlchemy and gRPC - providing automatic dependency injection, startup-time graph validation, and architectural guardrails so you can focus on business logic instead of wiring.

Seven ways in: **HTTP, WebSocket, gRPC, Unix sockets, MQTT, Modbus TCP and OPC UA** - one application, one dependency graph, one lifecycle. Talking to a PLC and serving a browser are the same kind of work here.

And it scales **without a process manager in front of it**. Since 0.8, `share_load()` plus a `count:` in the config makes the processes share one listening socket - no gunicorn, no supervisor, no nginx balancing between ports. Measured 2026-08-25: **1.97x throughput on two processes, 3.75x on four**.

```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.

### What it borrows from Spring Boot, and what it deliberately drops

The debt is real and worth naming: **starters**, and **failing at startup rather than in
production**. Ask for a dependency nothing can supply and the process refuses to boot,
with the class and parameter named.

What XIME drops is just as deliberate, because these are the parts that do not survive the
trip into Python:

| Spring | XIME |
|---|---|
| `@Service`, `@Autowired` - DI driven by annotations | Directory layout plus constructor type hints. No annotation is read for DI |
| `@Transactional` - AOP proxies rewriting your call | `async with self.transaction():` - the boundary is a line of code you can see |
| Prototype, request and session scopes | One scope: eager singleton. That is *why* the whole graph can be checked at startup |

So "Spring Boot for Python" is the wrong shorthand. The right one is **one dependency
graph, many front doors** - and one of those doors opens onto industrial hardware.

---

## Why not dependency-injector, injector, or lagom?

These are solid libraries. XIME used to lean on `dependency-injector` for its singleton storage layer, but as of 0.6 the registry is hand-rolled (a plain dict keyed by the class object), so XIME has no third-party DI dependency at all. The difference is scope:

| | dependency-injector / injector | lagom | XIME |
|---|---|---|---|
| Auto-scan packages by directory | No - manual wiring required | No | Yes |
| Startup-time graph validation | No | Partial | Yes - cycles, missing impl, ambiguous bindings |
| Code-first gRPC generation | No | No | Yes |
| Web framework integration | No | No | Yes - controllers, middleware, lifecycle |
| Explicit transaction management | No | No | Yes - `async with self.transaction():` |
| Designed for microservice structure | No | No | Yes |

If you only need DI, use `dependency-injector` or `lagom`. If you want a full convention layer that wires DI, HTTP, gRPC, transactions, and lifecycle together - use XIME.

---

## How It Works

```text
Application Code
      ↓
   XIME Core          ← scanning, DI, lifecycle, config
      ↓
  DI Container        ← core/container, built-in
      ↓
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
```

Adapters and starters are optional - install only what you need:

```bash
pip install "xime[web]"          # Uvicorn ASGI server
pip install "xime[sqlalchemy]"   # async DB sessions + transactions
pip install "xime[jwt]"          # JWT authentication
pip install "xime[scheduler]"    # cron-style task scheduling
pip install "xime[redis]"        # Redis client + cache backend
pip install "xime[grpc]"         # gRPC adapter (code-first)
pip install "xime[socket]"       # Unix domain socket IPC
pip install "xime[mqtt]"         # MQTT adapter (pub/sub + RPC over MQTT v5)
pip install "xime[s3]"           # S3 / MinIO storage backend
pip install "xime[mail]"         # SMTP email sending (aiosmtplib)
pip install "xime[modbus]"       # Modbus TCP adapter (master + slave)
pip install "xime[opcua]"        # OPC UA adapter (client + server)
pip install "xime[all]"          # everything above
```

> Requires **Python 3.12+**.

---

## Quick Start

**1. Define a controller** - a plain class; methods map to routes.

```python
# app/api/rest/user_controller.py
from xime.adapters.web.routing import get

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)
```

**2. Configure dependency injection** - declare which packages to scan and bind interfaces to implementations.

```python
# app/config/dependency.py
from xime import BindingConfig

dependency = BindingConfig()
dependency.scan("application.usecase", "infrastructure.repository")
dependency.bind({UserRepository: JpaUserRepository})
```

**3. Bootstrap the application.**

```python
# app/main.py
from xime import Application
from xime.adapters.web import WebAdapter

app = Application()
app.use(WebAdapter())
app.run()
```

**4. Run it.**

```bash
python -m app.main
```

<details>
<summary><b>Going further - multiple protocols & servers</b></summary>

```python
# 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
# Multiple servers in one process (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()
```

</details>

---

## 📦 Example Projects

The best way to learn XIME is to read real code. These open-source projects are built on the framework - clone them, run them, and use them as references for structuring your own service:

| Project | What it demonstrates | Good for |
| --- | --- | --- |
| [**xime-shop-example**](https://github.com/nguyen-huu-thang/xime-shop-example) | An e-commerce demo using a straightforward layered architecture. | 🟢 Getting started |
| [**data-service**](https://github.com/nguyen-huu-thang/data-service) | A production-grade microservice: Hexagonal / DDD, gRPC, SQLAlchemy, multi-tenant sharding. The most complete reference. | 🔵 Real-world patterns |
| [**notification-service**](https://github.com/nguyen-huu-thang/notification-service) | An async, IO-bound notification microservice with event-driven patterns. | 🔵 Async & events |
| [**xime-grpc-socket-example**](https://github.com/nguyen-huu-thang/xime-grpc-socket-example) | One app serving gRPC (code-first, dynamic mTLS) and Unix Domain Sockets side by side, with shared `@command` / `@stream` contracts and different security models. | 🟣 Multi-transport |

> New to XIME? Start with **xime-shop-example** for the fundamentals, then study **data-service** for full Hexagonal/DDD patterns at production scale. To see one app speak gRPC and sockets at once, read **xime-grpc-socket-example**.

---

## 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 |
| **Dynamic Binding** | Bind one `Protocol` to several impls (a tuple) and swap them app-wide at runtime via `Switcher`; off by default, consumers keep their code |
| **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; `async with self.read_only():` for reads |
| **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; typed server streaming with `@stream` + `yield` (no chunk wrapper, so a Java peer reads the `.proto` and understands it) |
| **gRPC Client SDK** | Generate a typed Pydantic client from `.proto`, inject via DI; deadlines, typed errors, automatic retry |
| **HTTPS** | TLS for the HTTP server via a `server.ssl` block in `application.yml`, including client-certificate verification; misconfiguration stops startup instead of silently serving plain HTTP |
| **Dynamic mTLS** | Certificate rotation without restart for both inbound servers and outbound clients |
| **Peer Identity** | gRPC reads the verified client cert into request context (fail-soft): `current_caller()` gives the CN, `current_peer_sans()` every Subject Alternative Name - raw and uninterpreted, so you match your own scheme (SPIFFE IDs or otherwise) |
| **Socket Adapter** | Unix Domain Socket IPC for same-host Native Engine calls (Linux); `@command` / `@stream` |
| **MQTT Adapter** | Message-driven transport for IoT/embedded: `@subscribe` (pub/sub) + `@rpc` (request/reply over MQTT v5); auto-reconnect; bounded concurrency |
| **Modbus Adapter** | Talk to PLCs directly: declarative device model that decodes registers (endianness, word order, scale), safe read planning, `@poll` / `@on_change`, and slave mode (`@serve` / `@on_write`) |
| **OPC UA Adapter** | Client and server for the modern industrial protocol: node models, real subscriptions (`@on_node_change`), all three security levels |
| **File Storage** | Backend-neutral `StorageService` (local filesystem / S3 / MinIO); bytes + streaming APIs; HTTP Range download and chunked upload helpers |
| **Multi-process** | `share_load()` turns one app into a supervised cluster: the `processes:` block decides which process opens which port, the parent holds the listening sockets, `run_once()` runs exactly once cluster-wide, and a watchdog restarts a silent child then promotes a new primary |
| **Shared Reference Data** | `RefData` - one copy in shared memory for data that **has** a durable source (JWT keys, app registry): the primary publishes, every process reads with no round trip |
| **Inter-process Store** | `Store` on LMDB for state with **no** durable source - rate limits, passkey challenges, replay protection; survives a process restart, and needs no Redis |
| **Inter-process Bus** | `ProcessLink` - commands and questions between processes, four distinct `ask` outcomes, per-channel ordering, each process owning its own write region |
| **Health Endpoints** | Opt-in `/healthz` and `/readyz` reporting per-process and cluster state; **off by default**, so nothing is exposed unless you ask for it |
| **Command-line Tools** | `xime init` scaffolds a project · `xime config --print` prints every key with its default · `xime check config` catches typos · `xime check module-level` catches work done at import time |

---

## Starters

Optional modules, similar to `spring-boot-starter-*`:

| Starter | What it provides | Status |
| --- | --- | --- |
| `xime.starters.sqlalchemy` | Async DB session, `SqlAlchemyTransactionManager`, `SqlAlchemyReadOnlyManager` (read-only blocks), `CrudRepository` (built-in CRUD) | ✅ Implemented |
| `xime.starters.jwt` | JWT signing, verification, middleware, **keys rotated by `kid`** | ✅ Implemented |
| `xime.starters.scheduler` | Cron-style task scheduling | ✅ Implemented |
| `xime.starters.cache` | `CacheService` abstraction (backend-neutral) | ✅ Implemented |
| `xime.starters.redis` | Async Redis client + `CacheService` backend | ✅ Implemented |
| `xime.starters.storage` | `StorageService` abstraction (object/blob store) | ✅ Implemented |
| `xime.starters.localfs` | Local filesystem `StorageService` backend | ✅ Implemented |
| `xime.starters.s3` | S3 / MinIO `StorageService` backend (multipart, presigned URL) | ✅ Implemented |
| `xime.starters.mail` | `MailService` abstraction + SMTP backend (async, HTML + text) | ✅ Implemented |

---

## 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**. The following are implemented: core DI (hand-rolled singleton registry, **no third-party DI dependency**) with **dynamic interface binding** (one Protocol → many impls, swapped at runtime), lifecycle, event bus, security context, configuration, JWT starter (audience/issuer enforcement, **keysets addressed by `kid`**, clock leeway, required claims), scheduler starter, SQLAlchemy starter, Cache + Redis starters, **Storage starter** (local filesystem + S3/MinIO) with **HTTP file streaming** (Range download, chunked upload), Web adapter (FastAPI + routing, pure-ASGI request-context & JWT middleware, custom middleware & exception handlers, **DI/config-aware middleware via `Inject`/`FromConfig` markers + first-class `configure_cors`**), gRPC adapter (proto-first + **code-first**, **typed server streaming**, **dynamic mTLS**), **gRPC client SDK** (typed, DI-injected, deadlines + typed errors + automatic retry), **Socket adapter** (Unix Domain Socket IPC), **MQTT adapter** (pub/sub + RPC over MQTT v5), **Modbus adapter** (declarative device model, master polling + slave mode), **OPC UA adapter** (node models, subscriptions, server mode, full security), multi-server support, **WebSocket** (`@ws` routing, handshake authentication over `Sec-WebSocket-Protocol`, close-on-token-expiry), and initialization order (`dependency.order()`).

**0.8 adds a multi-process runtime**: `share_load()` with a supervisor, watchdog and primary promotion; `RefData` (shared memory for data that has a durable source); `Store` on LMDB (state that has none); `ProcessLink` (inter-process bus); opt-in `/healthz` and `/readyz`; and the `xime init` / `xime config` / `xime check` command-line tools.

The core is covered by **2500+ tests**.

See the [CHANGELOG](https://github.com/nguyen-huu-thang/xime-framework/blob/main/CHANGELOG.md) for release history.

---

## 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 + read-only blocks |
| [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`; dynamic mTLS |
| [gRPC Client SDK](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/grpc-client.md) | Generate a typed client SDK; inject it via DI; deadlines, typed errors, retry, dynamic mTLS |
| [WebSocket](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/websocket.md) | `@ws` routes, token in a subprotocol, authentication before the handler, close on token expiry |
| [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 |
| [MQTT Adapter](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/mqtt.md) | Message-driven pub/sub + RPC over MQTT v5 for IoT/embedded |
| [Modbus Adapter](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/modbus.md) | Declarative device models, read planning, polling and slave mode for PLCs |
| [OPC UA Adapter](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/opcua.md) | Node models, subscriptions, server mode, and all three security levels |
| [File Storage](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/file-storage.md) | `StorageService` (local / S3 / MinIO) + HTTP Range download & chunked upload |
| [Inter-process Store](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/store.md) | Key-value store on LMDB for state with no durable source: rate limiting, passkey challenges, deduplication |
| [Shared reference data](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/refdata.md) | `RefData` - one copy in shared memory for JWT keys and the app registry: the primary publishes, every process reads |
| [Inter-process Bus](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/process-link.md) | `ProcessLink` - commands and questions between processes, four `ask` outcomes, per-channel ordering |
| [Command-line tools](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/cli.md) | `xime init` scaffolds a project · `xime config --print` prints every key with its default · `xime check config` catches typos |
| [Multi-process](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/multi-process.md) | `share_load()` - the `processes:` block, shared ports, supervisor, `run_once()`, primary promotion, watchdog, `/healthz`, and two probes for module-level code |
| [Event loop](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/event-loop.md) | Which loop is running, uvloop on Linux, and why it makes REST ~10% slower while making open-connection work 11-38% faster |
| [Starters](https://github.com/nguyen-huu-thang/xime-framework/blob/main/docs/en/starters.md) | SQLAlchemy, JWT, Scheduler, Cache, Redis, Storage (local / S3 + HTTP streaming) |
| [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 |

---

## Contributing

XIME is a solo project that needs community help to grow. There is still ground to cover: multi-process runtime, 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.

---

## License

Released under the [MIT License](https://github.com/nguyen-huu-thang/xime-framework/blob/main/LICENSE).
