README

README.md

Edifiko

Edifiko es una plataforma B2B que conecta a Arquitectos con Empresas Proveedoras de materiales de construcción. Permite a estudios de arquitectura gestionar cotizaciones, órdenes de compra y relaciones comerciales con proveedores de forma centralizada, con segregación estricta de datos por rol y organización.

El sistema define tres roles principales:

Rol	Descripción
`admin`	Supervisión global de la plataforma
`architect`	Comprador y planificador de proyectos
`supplier`	Proveedor de materiales y servicios

Stack Tecnológico

Capa	Tecnología
Framework	Next.js 16 (App Router) + React 19
Styling	Tailwind CSS v4 + Shadcn/UI (Radix primitives)
Backend	Firebase Cloud Functions v2
Base de datos	Firestore
Autenticación	Firebase Auth
Storage	Firebase Storage
Hosting	Firebase App Hosting
Validación y tipos	Zod (Single Source of Truth)
Testing	Vitest
Linting / Format	ESLint + Prettier + Husky + lint-staged
Package manager	pnpm

Estructura del Proyecto

edifiko/
├── app/                    # App Router de Next.js (páginas, layouts, globals.css)
│   ├── (dev)/ui/           # Entorno de Showcase de componentes (solo desarrollo)
│   ├── components/
│   │   ├── ui/             # Primitivos Shadcn/UI — NO modificar directamente
│   │   └── shared/         # Wrappers y utilidades compartidas
│   ├── hooks/shared/       # Custom Hooks reutilizables
│   └── utils/shared/       # Funciones utilitarias puras
├── adapters/
│   └── firebase-client-adapter/   # SDK de Firebase para el cliente (Auth, Firestore, Storage, Functions)
├── functions/
│   ├── src/                # Cloud Functions v2 (TypeScript)
│   └── adapters/firebase-admin-adapter/  # SDK Admin de Firebase
├── scripts/                # Setup de variables de entorno
├── .github/
│   ├── agents/             # Definiciones de agentes de IA
│   ├── skills/             # Skills de GitHub Copilot
│   └── workflows/          # GitHub Actions (CI)
└── public/                 # Assets estáticos y Service Worker (PWA)

Regla arquitectónica: No existe carpeta src/ en el frontend. Todo el código fuente reside directamente en la raíz del repositorio.

Primeros Pasos

Requisitos previos

Herramienta	Versión mínima
Node.js	20 LTS
pnpm	9+
Firebase CLI	Última
VS Code	1.95+
GitHub Copilot (extensión)	Última

1. Clonar el repositorio

bash

git clone <url-del-repositorio>
cd edifiko

2. Instalar dependencias

bash

# Dependencias del frontend
pnpm install

# Dependencias de Cloud Functions
cd functions && pnpm install && cd ..

3. Configurar variables de entorno

bash

# Genera los archivos .env.local automáticamente
pnpm setup-env:local

Esto ejecuta el script scripts/setup-env-local.mjs que genera el archivo .env.local con las claves de Firebase necesarias para desarrollo local.

4. Iniciar el servidor de desarrollo

bash

pnpm dev

Abre http://localhost:3000 en el navegador.

Variables de Entorno

El proyecto utiliza los siguientes scripts para gestionar las variables de entorno:

bash

pnpm setup-env         # Configura el entorno para despliegue
pnpm setup-env:local   # Configura el entorno para desarrollo local (.env.local)

Los archivos .env.local y .env nunca se commitean al repositorio. Contienen las claves del proyecto de Firebase (API Key, Auth Domain, Project ID, etc.).

Scripts Disponibles

bash

pnpm dev            # Servidor de desarrollo (Next.js + Webpack)
pnpm build          # Build de producción
pnpm start          # Inicia el servidor de producción
pnpm lint           # Analiza el código con ESLint
pnpm type-check     # Verificación de tipos con TypeScript sin emitir archivos
pnpm test           # Ejecuta los tests con Vitest
pnpm setup-env      # Configura variables de entorno para despliegue
pnpm setup-env:local  # Configura variables de entorno locales
pnpm mcp:setup      # Copia mcp-settings.example.json → mcp-settings.json (configuración del servidor MCP de Figma)
pnpm deploy:func:test # Despliega Cloud Functions al entorno de test

Firebase — Servicios e Infraestructura

App Hosting

El frontend Next.js se despliega mediante Firebase App Hosting, que gestiona automáticamente el build, el CDN y el escalado.

json

// firebase.json
"apphosting": {
  "backendId": "edifiko",
  "rootDir": "/"
}

El entorno de App Hosting se configura mediante apphosting.test.yaml (test) y apphosting.emulator.yaml (local).

Cloud Functions v2

Toda la lógica del servidor reside en functions/src/. Las funciones usan exclusivamente la Generación 2 de Cloud Functions.

bash

# Desplegar funciones al entorno de test
pnpm deploy:func:test

Las funciones pasan por lint y build antes de cada despliegue (configurado en firebase.json via predeploy).

Firestore

Base de datos principal del proyecto, organizada por colecciones con segmentación estricta por rol. Las reglas de seguridad se configuran en firestore.rules y los índices en firestore.indexes.json.

Región: us-central1
Acceso: Siempre mediado por la capa @/services/firebase/ — ningún componente accede directamente al SDK.

Firebase Auth

Gestiona la autenticación de los tres roles del sistema. La capa del cliente se encuentra en adapters/firebase-client-adapter/auth/.

Firebase Storage

Almacenamiento de archivos (imágenes de productos, documentos de proyectos, etc.). Las reglas se configuran en storage.rules. La capa del cliente se encuentra en adapters/firebase-client-adapter/storage/.

Emuladores de Firebase

El proyecto tiene los emuladores configurados para desarrollo completamente local:

Emulador	Puerto
App Hosting	5002
Auth	9099
Cloud Functions	5001
Firestore	8080
Storage	9199

bash

# Iniciar todos los emuladores
firebase emulators:start

Agentes de IA

El proyecto define un ecosistema de agentes especializados de GitHub Copilot en .github/agents/. Cada agente opera con reglas estrictas alineadas al dominio del proyecto.

`context-agent` — Orquestador Principal

Fuente de la verdad del proyecto. Define el modelo de negocio B2B, el stack tecnológico y las directivas arquitectónicas. Es el agente activo por defecto y orquesta a los demás.

@context-agent Revisa la arquitectura de este nuevo flujo

`Edifiko Designer` — Frontend & UI/UX

Experto en Tailwind v4, Shadcn/UI, Next.js App Router y fidelidad a Figma. Traduce diseños a componentes de producción, gestiona el Showcase y aplica tokens globales.

@designer Implementa la tarjeta de proveedor desde esta URL de Figma

`Firebase` — Backend & Seguridad

Arquitecto de Firestore Security Rules y Cloud Functions v2. Diseña esquemas Zod, servicios CRUD y lógica de servidor con segregación estricta por rol.

@firebase Crea el esquema Zod y el servicio Firestore para las órdenes de compra

`Core Architect` — Estratega de Producto

Coordinador full-stack. Planifica flujos complejos, organiza el App Router y coordina funcionalidades transversales como PDFs y notificaciones.

@architect Planifica el flujo de presupuesto entre el arquitecto y el proveedor

`QA Tester` — Aseguramiento de Calidad

Especialista en Vitest. Genera pruebas unitarias y de integración para servicios, hooks y funciones utilitarias, priorizando la lógica de negocio sobre los estilos visuales.

@qa-tester Escribe tests para el servicio de generación de PDFs

Skills de Copilot

Las skills son módulos de conocimiento especializado que los agentes invocan automáticamente según el contexto. Se encuentran en .github/skills/.

Figma

Skill	Función
`figma-code-connect`	Crea y mantiene archivos `.figma.ts/.figma.js` que mapean componentes Figma a snippets de código
`figma-create-design-system-rules`	Genera reglas personalizadas del design system para el proyecto
`figma-generate-design`	Traduce páginas de la app hacia Figma usando tokens del design system
`figma-implement-design`	Traduce diseños de Figma a código de producción con fidelidad 1:1
`figma-use`	Prerequisito obligatorio para cualquier escritura en el canvas de Figma

UI / Frontend

Skill	Función
`shadcn`	Gestiona componentes Shadcn/UI: agregar, buscar, corregir y componer
`tailwind-design-system`	Construye design systems con Tailwind CSS v4: tokens, patrones y componentes
`vercel-react-best-practices`	Optimización de React/Next.js: Server Components, data fetching, bundle
`web-design-guidelines`	Revisa accesibilidad (ARIA, navegación por teclado) y estándares UX

Skill	Función
`find-skills`	Descubre e instala nuevas skills disponibles
`skill-creator`	Crea, modifica y evalúa skills del proyecto

Integración Continua

El pipeline de CI se ejecuta en GitHub Actions (.github/workflows/ci.yml) y cubre los siguientes escenarios:

Push directo a main, dev o test
Pull Requests abiertos, sincronizados o marcados como "Ready for Review"
Los PRs en Draft no ejecutan el CI

Pasos del pipeline

Checkout → Install pnpm → Setup Node 20 → Install dependencies
  → Lint → Type-check → Tests (Vitest) → Build

El pipeline tiene cancelación automática de ejecuciones concurrentes para optimizar el uso de minutos de CI.

Requisitos para pasar a Code Review

pnpm lint sin errores
pnpm type-check sin errores
pnpm test sin fallos
pnpm build exitoso

Showcase de Componentes

El proyecto incluye un entorno de showcase dedicado accesible en:

http://localhost:3000/ui

Este entorno (ubicado en app/(dev)/ui/) está destinado exclusivamente a desarrollo y documenta visualmente cada componente del sistema de diseño.

Convención para nuevos componentes

Cada componente creado por el agente @designer debe incluir su página de showcase correspondiente con:

Casos de uso reales con datos mock tipados
Todas las variantes visuales del componente
Documentación de props e interfaces TypeScript
Validación de responsividad Mobile First

Primitivos del sistema de diseño

Los componentes base (app/components/ui/) son inmutables. Para casos de uso específicos se crean componentes compuestos en app/components/features/ que consumen estos primitivos.

Colaboración Diseñadores ↔ Agentes

El flujo de diseño a código de Edifiko integra Figma Desktop con GitHub Copilot mediante el protocolo MCP (Model Context Protocol).

Configurar el servidor MCP de Figma

Instalar el plugin "Figma MCP" en Figma Desktop (no funciona en la versión web).
Abrir el archivo del proyecto en Figma Desktop.
Ejecutar Plugins → Figma MCP → Start server (levanta en http://127.0.0.1:3845).
Copiar la configuración MCP: pnpm mcp:setup
En VS Code, verificar con Ctrl+Shift+P → MCP: List Servers que FigmaMCP esté en estado Running.
Abrir Copilot en modo Agent (Ctrl+Shift+I).

Flujo estándar de implementación

1. Seleccionar el frame en Figma Desktop
2. Copiar el node-id de la URL (ej: ?node-id=51-19 → 51:19 en la API MCP)
3. Solicitar al agente @designer con el node-id y el nombre del componente
4. El agente consulta el contexto de Figma, respeta los tokens de globals.css
   y genera el componente con su página de Showcase

Prompt de referencia:

node-id: 51:19
Genera el componente SupplierCard fiel al diseño de Figma.
Usa los tokens de color y tipografía de globals.css.

Reglas de implementación

Los tokens de diseño se definen en app/globals.css y se consumen como clases de Tailwind (text-primary, bg-surface, etc.). Prohibido hardcodear colores.
Los iconos provienen exclusivamente de lucide-react.
Todo componente es Server Component por defecto; 'use client' solo si requiere interactividad.
Las llamadas a Firebase se realizan siempre a través de @/services/firebase/, nunca desde componentes.

Para más detalle sobre este flujo, consulta CONTRIBUTING.md.

Flujo de Trabajo y Contribución

El proyecto sigue un proceso estructurado con Jira + GitHub. Los detalles completos se encuentran en WORKFLOW.md.

Ramas principales

Rama	Propósito
`main`	Producción estable
`test`	Integración y QA
`dev`	Desarrollo activo

Nomenclatura de ramas

[JIRA-ID]_[TIPO]_[nombre-de-la-tarea]

Ejemplos:
  ED-45_TASK_create-supplier-service
  ED-12_STORY_supplier-dashboard
  ED-58_BUG_fix-auth-token

Flujo rápido

bash

git checkout dev && git pull
git checkout -b ED-45_TASK_nombre-de-la-tarea

# ... desarrollar ...

pnpm lint && pnpm type-check && pnpm test && pnpm build

git add . && git commit -m "feat: descripción del cambio"
git push --set-upstream origin ED-45_TASK_nombre-de-la-tarea
# Abrir PR en GitHub

Versionado

El proyecto usa Semantic Versioning (MAJOR.MINOR.PATCH). Las versiones se gestionan con ramas BUMP_VX.Y.Z y se mergean hacia test antes de main.

README

Edifiko

Índice

Stack Tecnológico

Estructura del Proyecto

Primeros Pasos

Requisitos previos

1. Clonar el repositorio

2. Instalar dependencias

3. Configurar variables de entorno

4. Iniciar el servidor de desarrollo

Variables de Entorno

Scripts Disponibles

Firebase — Servicios e Infraestructura

App Hosting

Cloud Functions v2

Firestore

Firebase Auth

Firebase Storage

Emuladores de Firebase

Agentes de IA

context-agent — Orquestador Principal

Edifiko Designer — Frontend & UI/UX

Firebase — Backend & Seguridad

Core Architect — Estratega de Producto

QA Tester — Aseguramiento de Calidad

Skills de Copilot

Figma

UI / Frontend

Meta

Integración Continua

Pasos del pipeline

Requisitos para pasar a Code Review

Showcase de Componentes

Convención para nuevos componentes

Primitivos del sistema de diseño

Colaboración Diseñadores ↔ Agentes

Configurar el servidor MCP de Figma

Flujo estándar de implementación

Reglas de implementación

Flujo de Trabajo y Contribución

Ramas principales

Nomenclatura de ramas

Flujo rápido

Versionado

`context-agent` — Orquestador Principal

`Edifiko Designer` — Frontend & UI/UX

`Firebase` — Backend & Seguridad

`Core Architect` — Estratega de Producto

`QA Tester` — Aseguramiento de Calidad