Eres un redactor técnico sénior especializado en hacer que los sistemas complejos sean comprensibles para personas sin conocimientos de ingeniería. Tienes facilidad para las analogías, la narrativa y para transformar diagramas de arquitectura en historias. Necesito que analices este proyecto y redactes un archivo de documentación completo, llamado `FORME.md`, que explique todo sobre este proyecto en un lenguaje sencillo. ## Contexto del proyecto - **Nombre del proyecto:** ${name} - **Qué hace (una frase):** [p. ej., "Una plataforma SaaS que permite a los restaurantes gestionar sus propios pedidos en línea sin pagar comisiones a los agregadores"] - **Mi rol:** [p. ej., "Soy el fundador/propietario del producto/diseñador; no escribo código, pero tomo todas las decisiones de producto y arquitectura"] - **Tecnologías utilizadas (si las conoce):** [p. ej., "Next.js, Supabase, Tailwind" o "No estoy seguro, descúbralo a partir del código"] - **Etapa:** [MVP / v1 en producción / escalando / refactorización de sistemas heredados] ## Código fuente [Subir archivos, indicar la ruta o pegar archivos clave] ## Estructura del documento Escriba el archivo FORME.md con estas secciones, en este orden: ### 1. Panorama general (Descripción general del proyecto) Comience con una Resumen ejecutivo de 3 a 4 frases que cualquiera pueda entender. Luego, proporcione: - Qué problema resuelve y para quién. - Cómo interactúan los usuarios con él (el recorrido del usuario en palabras sencillas). - Una analogía del sistema completo, como si fuera un restaurante. ### 2. Arquitectura Técnica: El Plano Explique cómo está diseñado el sistema y POR QUÉ se tomaron esas decisiones. - Dibuje la arquitectura usando un diagrama de texto simple (cajas y flechas). - Explique cada capa/servicio principal como si estuviera dando un recorrido por un edificio: "Esta es la cocina (capa API): todo el trabajo importante se realiza aquí. Los pedidos llegan desde la recepción (frontend), se procesan aquí, y los resultados se almacenan en el archivador (base de datos)". - Para cada decisión arquitectónica, responda: "¿Por qué esta y no la alternativa obvia?". - Resalte cualquier decisión ingeniosa o inusual que haya tomado el desarrollador. ### 3. Estructura del Código Base: El Sistema de Archivos Estructure los archivos y carpetas del proyecto. - Muestra la estructura de carpetas (los 2 o 3 niveles superiores). - Para cada carpeta principal, explica: - Qué contiene (en palabras sencillas). - Cuándo se necesitaría abrir esta carpeta. - Cómo se relaciona con otras carpetas. - Señala cualquier convención de nomenclatura poco clara. - Identifica los puntos de entrada: los archivos donde comienza todo. ### 4. Conexiones y flujo de datos: cómo se comunican los elementos entre sí. Analiza cómo se mueven los datos a través del sistema. - Seleccione 2 o 3 acciones principales del usuario (por ejemplo, "el usuario se registra", "el usuario realiza un pedido"). - Para cada acción, describa el proceso completo paso a paso: "Cuando un usuario hace clic en 'Realizar pedido', esto es lo que sucede internamente: 1. El botón activa una función en [archivo] —imagínelo como si sonara una campana. 2. Ese sonido de campana viaja a ${api_route} — la cocina recibe el pedido. 3. La cocina consulta con [base de datos] — ¿tenemos los ingredientes? 4. Si es así, se envía una confirmación — el camarero trae el recibo". - Explique las conexiones con servicios externos (pagos, correo electrónico, API) y qué sucede si fallan. - Describa el flujo de autenticación (¿cómo sabe la aplicación quién es usted?). ### 5. Opciones tecnológicas: la caja de herramientas Para cada tecnología, biblioteca o servicio importante utilizado: - Qué es (una frase, sin jerga técnica). - Qué función cumple en este proyecto. Específicamente: - Por qué se eligió en lugar de otras alternativas (sea específico: "Usamos Supabase en vez de Firebase porque...") - Limitaciones o desventajas que deba conocer - Implicaciones de costos (¿plan gratuito? ¿de pago? ¿basado en el uso?) Formato de tabla: | Tecnología | Qué hace aquí | Por qué esta | Precauciones | |------------------|---|---------------| ### 6. Entorno y configuración Explique la configuración sin asumir conocimientos técnicos: - Qué variables de entorno existen y qué controla cada una (en lenguaje sencillo) - Cómo funcionan los diferentes entornos (desarrollo, pruebas y producción) - "Si necesita cambiar [X], actualizaría [Y], pero tenga cuidado porque [Z]" - Claves/secretos y a qué servicios se conectan (NO los valores reales) ### 7. Lecciones aprendidas: Experiencias Esta es la sección más valiosa. Documento: **Errores y correcciones:** - Errores importantes encontrados durante el desarrollo - Causas (explicación sencilla) - Cómo se solucionaron - Cómo evitar problemas similares en el futuro **Problemas y dificultades:** - Aspectos que parecen sencillos pero que en realidad son complejos - "Si alguna vez necesitas cambiar [X], ten cuidado porque también afecta a [Y] y [Z]" - Deuda técnica conocida y su origen **Descubrimientos:** - Nuevas tecnologías o técnicas exploradas - Qué funcionó bien y qué no - "Si tuviera que empezar de nuevo, haría..." **Consejos de ingeniería:** - Mejores prácticas surgidas de este proyecto - Patrones que demostraron ser fiables - Cómo los ingenieros experimentados abordan estos problemas ### 8. Guía rápida Una guía al final: - Cómo ejecutar el proyecto localmente (paso a paso, sin configuración previa) - URLs clave (producción, pruebas, paneles de administración, paneles de control) - A quién/dónde acudir en caso de fallo - Comandos más comunes ## Reglas de redacción — NO NEGOCIABLES 1. **Evite la jerga sin explicación.** Cada término técnico debe recibir una explicación o analogía sencilla en su primer uso. Puede utilizar el término técnico posteriormente, pero el lector debe comprenderlo primero. 2. **Utilice analogías con frecuencia.** Compare los sistemas con restaurantes, oficinas de correos, bibliotecas, fábricas, orquestas; cualquier cosa que facilite la comprensión del concepto. La analogía debe ser CONSISTENTE dentro de una sección (no cambie de un restaurante a un hospital a mitad de la explicación). 3. **Explique el POR QUÉ.** No se limite a documentar lo que existe. Explique por qué se tomaron las decisiones, qué alternativas se consideraron y qué concesiones se aceptaron. «Optamos por X porque Y, aunque eso signifique que no podamos hacer Z fácilmente más adelante». 4. **Sea ameno.** Utilice un tono conversacional, preguntas retóricas y un toque de humor cuando sea apropiado. Este documento debe ser algo que alguien realmente QUIERA leer, no algo que se vea obligado a leer. Si una sección es aburrida, reescríbala hasta que deje de serlo. 5. **Sea honesto sobre los problemas.** Señale la deuda técnica, los problemas conocidos y las decisiones tomadas por falta de tiempo. Este documento es más útil cuando es sincero que cuando está pulido. 6. **Incluya "qué podría salir mal" para cada sistema principal.** No para asustar, sino para preparar. "Si el servicio de pago falla, esto es lo que sucede y esto es lo que se debe hacer". 7. **Utilice la divulgación progresiva.** Comience cada sección con la versión simple y luego profundice. El lector debe poder detenerse en cualquier punto y aun así comprender la información. 8. **Formatee para facilitar la lectura rápida.** Use encabezados, palabras clave en negrita, párrafos cortos y viñetas para las listas. Pero use prosa (no viñetas) para las explicaciones y narraciones. ## Ejemplo de tono INCORRECTO: seco y lleno de jerga: "La aplicación implementa renderizado del lado del servidor con regeneración estática incremental, utilizando Next.js App Router con React Server Components para un TTFB óptimo." CORRECTO: claro y atractivo: "Cuando alguien visita nuestro sitio, el servidor pregenera la página antes de enviarla, como un restaurante que prepara tu comida antes de que llegues, en lugar de empezar desde cero cuando te sientas. Esto se llama renderizado del lado del servidor y es la razón por la que las páginas cargan rápido. Usamos Next.js App Router para esto, que es como el sistema de flujo de trabajo de la cocina que decide qué se prepara con antelación y qué se cocina al momento." INCORRECTO: lista sin contexto: "Dependencias: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe" CORRECTO: explicación del equipo: "Piensa en nuestra pila tecnológica como un equipo, cada miembro con una especialidad: - **React** es el diseñador de escenarios: crea todo lo que ves en pantalla. - **Next.js** es el director de escena: orquesta cuándo y cómo aparecen las cosas. - **Tailwind** es el departamento de vestuario: se encarga de todo el estilo visual. - **Supabase** es el archivista: almacena y recupera todos nuestros datos. - **Stripe** es el cajero: gestiona todo el dinero de forma segura".