Ordit RS - Guia de producto

1. Que es Ordit

Ordit es una herramienta para crear automatizaciones pequenas y confiables sin tener que construir una aplicacion completa alrededor. Sirve para tomar una entrada, procesarla con codigo propio y entregar un resultado.

Escucha

Detecta archivos nuevos, mensajes, requests, horarios o entradas desde adapters.

Procesa

Ejecuta codigo simple para transformar, validar, enriquecer o decidir.

Entrega

Guarda archivos, publica eventos, responde por HTTP o conecta el resultado con otro flujo.

2. Arquitectura en una pagina

Ordit separa el cliente de operacion, el proceso que ejecuta y el runtime que orquesta entradas, acciones y salidas. Esta separacion permite que una automatizacion sea facil de usar sin convertir al CLI en el servicio productivo.

ordit Cliente para construir, listar, correr, detener e inspeccionar.

API local Canal operativo entre el cliente y el proceso vivo.

orditd Mantiene runs, adapters, estado y shutdown ordenado.

runtime Ejecuta triggers, handlers, reglas de flujo y outputs.

adapters Conectan archivos, HTTP, RabbitMQ, SQS, S3, CRON y extensiones.

Flujo principal

entrada detectada
  -> evento normalizado
  -> handler(input, context)
  -> return Ok(value)
  -> dispatch a uno o mas outputs
  -> logs estructurados por correlationId

Secuencia de ejecucion

usuario -> ordit: ordit run acme/job:dev
ordit -> orditd: comando Run por API local
orditd -> runtime: iniciar run
runtime -> trigger: detectar archivo, mensaje, HTTP o CRON
runtime -> handler: ejecutar codigo del usuario
handler -> runtime: Ok / Err / Fatal / Retry / Dlq / undefined
runtime -> outputs: entregar resultado si corresponde
runtime -> observabilidad: registrar eventos estructurados

La documentacion tecnica completa incluye diagramas Mermaid de build, run, compose, adapters, observabilidad y puntos de extension: docs/architecture.md.

3. Casos de uso

Ordit encaja cuando una automatizacion debe ser facil de crear, versionar, distribuir y ejecutar en entornos distintos.

Procesar archivos

Tomar documentos de una carpeta, normalizarlos y escribir una salida procesada.

Ejecutar tareas programadas

Generar reportes, sincronizar datos o disparar controles cada cierto horario.

Encadenar flujos

Hacer que una tarea produzca un evento y otra tarea continue el proceso.

Integrar sistemas

Recibir desde HTTP, RabbitMQ o SQS y entregar el resultado a archivos, eventos o colas.

Automatizar comunicaciones

Construir adapters para email, Telegram o sockets cuando el canal sea parte del flujo.

Consultar datos

Disparar procesos desde consultas a base de datos, objetos en S3 o reglas de negocio externas.

4. Primer flujo

El camino basico es empaquetar una automatizacion, verla en el inventario y ejecutarla sobre un workspace.

ordit build -t acme/ordit-echo:dev -f ./Orditfile .
ordit ls
ordit run acme/ordit-echo:dev

Si el flujo escucha una carpeta de entrada, crear un archivo dispara la ejecucion:

mkdir -p input
printf 'hola ordit' > input/hola.txt

5. Crear una automatizacion

Una automatizacion se describe con un Orditfile. Ese archivo declara el nombre del paquete, el archivo que contiene la accion, cuando se activa y donde entregar el resultado.

NAME acme/ordit-echo
VERSION dev
HANDLER echo
ENTRY ./handlers/echo.mjs
TRIGGER file.changed directory=./input eventType=file.created
OUTPUT file.write directory=./output
OUTPUT queue.publish queue=events.created

Accion

La accion recibe la entrada y devuelve el valor que Ordit debe entregar.

export async function handler(input, context) {
  return Ok({
    fileName: input.fileName,
    text: `${input.fileName}: ${input.content}`
  });
}

6. Capacidades

Ordit combina entradas, acciones y salidas. El producto trae adapters minimos para trabajar en escenarios reales y deja abierto el camino para sumar nuevos adapters por proyecto, equipo o tercero.

Entradas

Archivos, HTTP, RabbitMQ, SQS, tiempo y eventos internos.

Acciones

Codigo propio para transformar, validar, enrutar, enriquecer o decidir.

Salidas

Archivos, HTTP, RabbitMQ, SQS, eventos internos y colas locales; extensible a S3 y otros destinos.

Necesidad	Como se resuelve
Responder a un archivo nuevo	Usar el adapter de archivos como entrada.
Recibir eventos empresariales	Usar RabbitMQ, SQS o eventos internos.
Exponer un webhook	Usar HTTP como entrada del flujo.
Ejecutar todos los dias o cada X minutos	Usar CRON como entrada por tiempo.
Generar varios resultados	Declarar mas de una salida para el mismo flujo.
Reutilizar una automatizacion	Empaquetarla con nombre y version para instalarla o correrla despues.
Crear procesos de varios pasos	Combinar flujos y eventos con compose.

7. Adapters provistos y posibles

Ordit no debe limitarse a un tipo de entrada o salida. El set provisto cubre automatizacion local, integracion por colas, webhooks y eventos. El mismo modelo permite agregar adapters nuevos sin cambiar como se define una automatizacion.

Provistos por Ordit

Archivos

Observar carpetas, leer entradas de archivos y escribir resultados.

HTTP

Recibir webhooks o requests y entregar respuestas o llamadas salientes.

RabbitMQ

Consumir y publicar mensajes en flujos empresariales basados en AMQP, con exchange, routing key, prefetch y politica de ack.

SQS

Consumir y publicar mensajes en colas administradas de AWS.

Eventos internos

Encadenar automatizaciones dentro de un compose sin depender de infraestructura externa.

CRON

Disparar tareas por horario para reportes, sincronizaciones o controles periodicos.

Extensibles por proyecto o terceros

Adapter posible	Uso esperado
Email	Recibir correos, procesar adjuntos o enviar notificaciones.
Telegram	Convertir mensajes de chat en entradas de automatizacion o enviar respuestas.
Sockets	Trabajar con conexiones persistentes, telemetria o eventos en tiempo real.
S3	Reaccionar a objetos nuevos o publicar resultados en buckets.
Base de datos	Disparar procesos desde queries, cambios detectados o jobs de conciliacion.
APIs internas	Conectar productos propios sin duplicar logica de ejecucion.

8. Combinar automatizaciones

Compose permite declarar varios pasos en un solo archivo. Es util cuando una automatizacion necesita recibir algo, procesarlo, emitir un evento y continuar con otra accion.

version: '1'
settings:
  intervalMs: 1000
  maxEventDepth: 16
  maxQueuedEvents: 10000
handlers:
  source:
    modulePath: ./handlers/source.mjs
    workspace: ./runtime/source
    sandbox: network-limited
    networkAllowlist:
      - api.example.com
    trigger:
      type: cron
      expression: "*/5 * * * *"
      eventType: timer.tick
  sink:
    modulePath: ./handlers/sink.mjs
    workspace: ./runtime/sink
    sandbox: workspace
    trigger:
      type: event
      event: timer.tick
      source: compose.dispatch

ordit compose up --config ./ordit-compose.yaml

9. Operar automatizaciones

Una automatizacion debe poder ser revisada, ejecutada y atendida sin abrir el codigo. Por eso Ordit prioriza inventario, paquetes versionados, ejecucion explicita y documentacion local.

Inventario

Lista las automatizaciones disponibles y elimina las que ya no uses.

Ejecucion controlada

Corre una automatizacion por nombre y elige el workspace donde debe trabajar.

Uso local

La guia puede instalarse junto al cliente para consulta offline.

ordit ls
ordit run --cwd ./workspace acme/ordit-echo:dev
ordit rm acme/ordit-echo:dev
ordit docs

10. Referencia rapida

ordit --help
ordit build -t <image:tag> -f ./Orditfile .
ordit ls
ordit run <image:tag>
ordit run --cwd /tmp/workspace <image:tag>
ordit run <image:tag> --input-json '{"value":1}'
ordit rm <image:tag>
ordit compose up --config ./ordit-compose.yaml
ordit docs