Saltar al contenido principal

Habilitación Inicial de Herramientas para Nuevos Proyectos en Brace

Este documento define el proceso completo de habilitación de herramientas y configuración de infraestructura al iniciar un nuevo proyecto de desarrollo en Brace. El objetivo es garantizar que todo esté listo antes de comenzar el desarrollo, reduciendo bloqueos técnicos y permitiendo al equipo centrarse en construir valor desde el día uno.

1. Creación del Repositorio​

Cada nuevo proyecto debe contar con un repositorio creado desde el boilerplate oficial de Brace, el cual contiene una estructura de monorepositorio dividida en:

  • web/ para la aplicación web
  • api/ para los servicios API y lógica de negocio Acciones a realizar:
  • Crear repositorio nuevo desde la organización en GitHub
  • Generado con base al boilerplate
  • Configurar ramas principales: develop, stage, production
  • Establecer reglas de protección para develop, stage, production
  • Estos ambientes deben contar con sus propios recursos: bucket S3, base de datos, pools de usuarios, etc.

2. Paso a Paso para Integración de Repositorio Lovable en Web​

2.1 Preservación de Estándares​

  • Conservar archivos de rest-client:
    • web/src/rest-client/verbs.ts
    • web/src/rest-client/verbs-utils.ts
  • Crear una copia de la carpeta rest-client con estos archivos

2.2 Limpieza e Integración​

  • Eliminar todo el contenido de la carpeta web/
  • Copiar todo el contenido del repositorio Lovable a la carpeta web/ (se recomienda la última versión funcional)
  • No copiar la carpeta .git del repositorio Lovable

2.3 Restauración de Estándares​

  • Restaurar los archivos de rest-client preservados:
    • verbs.ts y verbs-utils.ts a web/src/rest-client/
  • Adaptar package.json y configuraciones para el contexto del monorepositorio

2.4 Verificación​

  • Instalar dependencias en web/
  • Probar que el proyecto compile y funcione correctamente
  • Verificar que la comunicación con la API funcione

2.5 Opcional​

  • Mantener el repositorio Lovable original (con su carpeta .git) en la carpeta web/ del monorepositorio para futuras referencias o actualizaciones del repositorio en Lovable.

3. Configuración de Servicios en AWS​

Para permitir el despliegue y funcionamiento del sistema, se debe configurar la infraestructura básica en AWS. Esto incluye:

Servicios a configurar:​

  • Cognito: Para la autenticación de usuarios, se deben crear pools de usuarios por ambiente.
  • S3: Buckets separados por ambiente para almacenar archivos públicos y privados.
  • RDS: Instancias de base de datos para los distintos entornos.
  • Amplify: Despliegue automático del frontend.
  • Lambda: Para ejecutar funciones del backend sin servidor. Nota: Estos servicios deben ser configurados inicialmente en la cuenta de AWS de la empresa, a menos que el proyecto requiera uso directo de la cuenta del cliente.

4. Seguridad y Perfiles IAM​

Es fundamental establecer controles de acceso desde el inicio del proyecto. Los desarrolladores deben tener únicamente los permisos necesarios. Acciones a realizar:

  • Crear perfiles IAM para cada miembro del equipo
  • Asignar permisos mínimos y específicos según su rol
    • Ejemplo: acceso solo a buckets dev, a instancias RDS no productivas, etc.
  • Configurar monitoreo de accesos para auditoría

5. Variables de Entorno​

Es necesario generar archivos .env específicos por cada ambiente para gestionar variables de configuración sensibles y específicas. Contenido típico:

  • URLs de APIs
  • Claves de acceso a servicios (Cognito, S3, RDS)
  • Parámetros de despliegue
  • Integraciones con servicios externos (ej: Stripe, Auth0, etc.) Acciones:
  • Crear y versionar archivos .env.example como referencia
  • Configurar variables reales en entornos seguros (AWS Parameter Store, GitHub Secrets, etc.)

6. Verificación Inicial del Entorno​

Antes de comenzar el desarrollo:

  • Verificar que cada desarrollador pueda clonar y correr el proyecto localmente
  • Realizar un primer despliegue exitoso del frontend con Amplify y del backend en Lambda o servidor correspondiente
  • Validar que los servicios básicos estén funcionando (login, rutas públicas, base de datos operativa)

Historia de Usuario: Habilitación de Herramientas Iniciales Nombre: Habilitación de Herramientas Iniciales para Proyecto Descripción: Como líder técnico, quiero tener todas las herramientas necesarias configuradas antes de iniciar el sprint, para que el equipo pueda trabajar sin bloqueos técnicos y con ambientes correctamente estructurados. Criterios de Aceptación:

  • Se creó un repositorio basado en el boilerplate oficial.
  • Se configuraron los servicios básicos en AWS: Cognito, S3, RDS, Amplify, Lambda.
  • Se asignaron perfiles IAM a los desarrolladores con acceso mínimo necesario.
  • Se crearon los ambientes: producción, stage y desarrollo, cada uno con sus recursos independientes.
  • Se generaron archivos .env con las variables necesarias.
  • Se realizó el primer deploy exitoso.
  • Los desarrolladores tienen el entorno listo y funcional en local.

Este documento debe evolucionar con el tiempo para incluir nuevas herramientas, servicios o mejores prácticas asociadas al inicio de proyectos en Brace. Se recomienda revisarlo periódicamente y actualizarlo tras cada nuevo proyecto importante.