Diseño de sistemas: dibujar tu herramienta

Resumen

Una herramienta de investigación es un sistema: partes que se piden cosas entre sí. Dibujarla te obliga a saber qué hace cada parte, le da al agente un mapa antes de pedirle un cambio y le deja a quien herede el proyecto una forma de entenderlo sin leer todo el código.

1. 1

   La caja negra

   Antes de abrirla, describe la herramienta desde fuera: qué entra (una respuesta al cuestionario, una consulta) y qué sale (una fila guardada, un tablero al día). Si no puedes decir qué entra y qué sale, todavía no sabes qué construiste.

2. 2

   Las partes

   El servidor recibe las solicitudes y decide qué hacer con ellas. La base de datos guarda las respuestas. El worker es un proceso aparte que hace el trabajo lento sin hacer esperar a nadie, como mandar respuestas abiertas al modelo de lenguaje, que contesta por su API.

3. 3

   El diagrama en el repositorio

   Mermaid describe un diagrama con texto: cada línea dice quién le pide qué a quién. Como es texto, vive en un archivo de tu repositorio, Git registra sus cambios junto con los del código y muchos visores de Markdown lo dibujan. Un diagrama de secuencia muestra el orden de los mensajes.

El diagrama de secuencia de tu encuesta: quién le pide qué a quién, desde que alguien responde hasta que cambia el tablero.