> ## Documentation Index
> Fetch the complete documentation index at: https://pulian.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Example-first overview of Hile packages and AI-facing usage rules.

# Hile

Hile is a lightweight Node.js service toolkit for HTTP APIs, Next.js apps, reusable models, message-based microservices, jobs, and Redis-backed reliability primitives.

The docs in this repository are generated from the same AI context that powers `skills/hile/`, `llms.txt`, `llms-full.txt`, and every package `AI.md`.

## Core Mental Model

* `@hile/core` manages resources as async services. A boot file starts things; `shutdown()` callbacks release them.
* `@hile/http` exposes Koa routes and file-system controllers.
* `@hile/model` is the reusable business-logic layer. Controllers and Next.js pages should call models instead of duplicating domain logic.
* `@hile/micro` uses message loaders and WebSocket clients for service discovery and RPC.
* Redis primitives (`redis-lock`, `redis-idempotency`, `redis-rate-limit`, `redis-stream-queue`, `cache`) are distributed coordination helpers, not exactly-once systems.

## Package Selection Matrix

| User asks for                                                      | Use                                          | Also read                                                              |
| ------------------------------------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------- |
| Start an app, manage lifecycle, graceful shutdown                  | `@hile/core`, `@hile/cli`, `@hile/bootstrap` | `packages/core-lifecycle.md`                                           |
| Create an HTTP endpoint or Koa middleware                          | `@hile/http`                                 | `packages/http.md`, `recipes/http-api-model-typeorm.md`                |
| Run Next.js and API controllers on one port                        | `@hile/http-next`                            | `packages/http-next.md`, `recipes/http-next-fullstack.md`              |
| Put business logic somewhere reusable                              | `@hile/model`                                | `packages/model-context.md`                                            |
| Propagate request id, tenant id, logger bindings, or micro context | `@hile/context`                              | `packages/model-context.md`                                            |
| Connect to SQL through TypeORM                                     | `@hile/typeorm`                              | `packages/core-lifecycle.md`, `packages/infrastructure.md`             |
| Connect to Redis                                                   | `@hile/ioredis`                              | `packages/core-lifecycle.md`, `packages/infrastructure.md`             |
| Create structured logs                                             | `@hile/logger`                               | `packages/core-lifecycle.md`, `packages/infrastructure.md`             |
| Add read-through Redis cache                                       | `@hile/cache`                                | `packages/infrastructure.md`, `recipes/redis-cache-singleflight.md`    |
| Run cron or delayed jobs                                           | `@hile/schedule`                             | `packages/infrastructure.md`                                           |
| Build a custom file loader or understand route mapping             | `@hile/loader`                               | `packages/infrastructure.md`                                           |
| Add request/response messaging over WS/IPC/worker                  | `@hile/message-*`                            | `packages/messaging-micro.md`                                          |
| Load file-based message handlers                                   | `@hile/message-loader`                       | `packages/messaging-micro.md`, `recipes/micro-rpc-message-loader.md`   |
| Build service discovery or RPC                                     | `@hile/micro`                                | `packages/messaging-micro.md`, `recipes/micro-rpc-message-loader.md`   |
| Push runtime config without restarts                               | `@hile/micro-dynamic-configs`                | `packages/messaging-micro.md`, `recipes/runtime-config.md`             |
| Stabilize config-driven runtime reloads                            | `@hile/reloader`                             | `packages/reloader.md`, `recipes/stable-runtime-reload.md`             |
| Compose topics, config, and reloader state as refs                 | `@hile/reactivity`                           | `packages/reactivity.md`, `recipes/stable-runtime-reload.md`           |
| Protect a critical section with a lease                            | `@hile/redis-lock`                           | `packages/redis-reliability.md`                                        |
| Stop duplicate retry side effects                                  | `@hile/redis-idempotency`                    | `packages/redis-reliability.md`, `recipes/queue-worker-idempotency.md` |
| Enforce shared quotas or 429s                                      | `@hile/redis-rate-limit`                     | `packages/redis-reliability.md`                                        |
| Persist and retry background jobs                                  | `@hile/redis-stream-queue`                   | `packages/redis-reliability.md`, `recipes/queue-worker-idempotency.md` |
| Scaffold a new project                                             | `create-hile`                                | `packages/create-hile.md`, `recipes/new-project-scaffold.md`           |

## Common Selection Rules

* If the task is a user-facing API, start with `@hile/http` or `@hile/http-next`.
* If the task is reusable business behavior, put it in `@hile/model` even if the caller is HTTP, Next.js, queue, or micro.
* If the task may retry or redeliver and has side effects, add `@hile/redis-idempotency`.
* If the task is background work, use `@hile/redis-stream-queue`; do not use micro RPC as a queue.
* If the task is "only one replica should run this", use `@hile/redis-lock` or `@hile/schedule` distributed mode, and keep a final business consistency wall.
* If the task is "prevent too many attempts", use `@hile/redis-rate-limit`; do not confuse it with authentication or idempotency.
* If config changes can arrive in bursts, use `@hile/reloader` around the runtime; do not reload directly inside every subscribe callback.
* If service code needs refs or async watch strategies for topics/config/reloader state, use `@hile/reactivity`.

## Start With Examples

For implementation tasks, pick the package from the matrix and copy the closest recipe before writing custom abstractions.

* HTTP API + model + TypeORM: `docs/ai/recipes/http-api-model-typeorm.md`
* HttpNext fullstack app: `docs/ai/recipes/http-next-fullstack.md`
* Redis cache with singleflight: `docs/ai/recipes/redis-cache-singleflight.md`
* Queue worker with idempotency: `docs/ai/recipes/queue-worker-idempotency.md`
* Micro RPC with message loader: `docs/ai/recipes/micro-rpc-message-loader.md`
* Runtime dynamic config: `docs/ai/recipes/runtime-config.md`
* New scaffolded project: `docs/ai/recipes/new-project-scaffold.md`