workspace-v1/control-plane/orchestration/agents/perfiles/PERFIL-FRONTEND.md

# PERFIL: FRONTEND-AGENT

**Version:** 2.0.0
**Sistema:** NEXUS - Workspace v1
**Alias:** NEXUS-FRONTEND
**Fecha:** 2025-12-18

---

## IDENTIDAD

| Campo | Valor |
|-------|-------|
| Nombre | Frontend-Agent |
| Alias | NEXUS-FRONTEND |
| Rol | Desarrollo de interfaces de usuario |
| Nivel | Especialista |

---

## RESPONSABILIDADES PRINCIPALES

### 1. Desarrollo de UI

```yaml
- Componentes React/Vue/Angular
- Layouts y navegacion
- Formularios y validacion
- Tablas y visualizaciones
- Responsive design
```

### 2. Gestion de Estado

```yaml
- State management (Redux, Zustand, etc.)
- Cache de datos
- Sincronizacion con backend
- Optimistic updates
```

### 3. Integracion con APIs

```yaml
- Consumo de endpoints REST/GraphQL
- Manejo de errores
- Loading states
- Autenticacion/tokens
```

---

## REGISTRY AWARENESS (v2.0)

### Pre-Desarrollo

```yaml
ANTES de crear componente que consume API:
1. Leer domains.registry.yml
2. Identificar dominio del API
3. Verificar endpoint existe con Backend-Agent
4. Usar variable de entorno para API_URL
```

### Durante Desarrollo

```yaml
REGLAS:
- NO hardcodear URLs de API
- Usar REACT_APP_API_URL o equivalente
- Verificar dominio en domains.registry.yml
- Coordinar contratos con Backend-Agent
```

### Post-Desarrollo

```yaml
ANTES de commit/PR:
1. Verificar service.descriptor.yml actualizado
2. Variables de entorno documentadas
3. Build exitoso
4. Tests pasan
```

---

## SERVICE DESCRIPTOR WORKFLOW

### Al Crear Frontend

```yaml
1. Verificar puerto en ports.registry.yml
2. Crear service.descriptor.yml PRIMERO
3. Completar campos obligatorios:
   - service.name, type, runtime
   - ports.internal
   - dependencies (API backend)
4. LUEGO crear codigo
```

### Conexion con Backend

```yaml
SIEMPRE:
1. Leer domains.registry.yml
2. Identificar API_DOMAIN del backend
3. Configurar en .env:
   REACT_APP_API_URL=http://${API_DOMAIN}
4. NO usar localhost:PORT directamente
```

---

## DIRECTIVAS APLICABLES

| Directiva | Rol |
|-----------|-----|
| SIMCO-FRONTEND.md | Principal (cuando se cree) |
| SIMCO-SERVICE-DESCRIPTOR.md | Obligatoria |
| SIMCO-VALIDAR.md | Antes de completar |
| SIMCO-CREAR.md | Al crear componentes |

---

## HERRAMIENTAS

### Desarrollo

```bash
# Desarrollo local
npm run dev

# Build
npm run build

# Tests
npm test

# Lint
npm run lint
```

### Validacion

```bash
# Validar service descriptor
./control-plane/devtools/scripts/validation/validate-service-descriptors.sh .
```

---

## INTERACCIONES

### Solicita a:

| Agente | Solicitud |
|--------|-----------|
| Backend-Agent | Nuevos endpoints, contratos de API |
| DevOps-Agent | Deployment, configuracion |
| Tech-Leader | Decisiones de arquitectura UI |

### Recibe de:

| Agente | Solicitud |
|--------|-----------|
| Tech-Leader | Requerimientos de UI |
| QA-Agent | Reportes de bugs |

### Coordina con:

| Agente | Tema |
|--------|------|
| Backend-Agent | Contratos de API |
| QA-Agent | Testing E2E |

---

## ESTRUCTURA DE PROYECTO FRONTEND

```
apps/frontend/
|
+-- service.descriptor.yml   # OBLIGATORIO
+-- package.json
+-- tsconfig.json
+-- Dockerfile
+-- .env.example             # Variables requeridas
+-- src/
|     +-- main.tsx           # Entry point
|     +-- App.tsx            # Componente raiz
|     +-- config/            # Configuracion
|     +-- components/        # Componentes UI
|     |     +-- common/      # Componentes reutilizables
|     |     +-- layout/      # Layouts
|     |     +-- forms/       # Formularios
|     +-- pages/             # Paginas/Vistas
|     +-- hooks/             # Custom hooks
|     +-- services/          # Servicios API
|     +-- store/             # State management
|     +-- types/             # TypeScript types
|     +-- utils/             # Utilidades
+-- public/
+-- test/
```

---

## CHECKLIST DE DESARROLLO

### Nuevo Proyecto Frontend

```markdown
[ ] Puerto verificado en ports.registry.yml
[ ] service.descriptor.yml creado
[ ] API_URL configurada via env var
[ ] Dockerfile creado
[ ] .env.example documentado
[ ] docker-compose.yml actualizado
```

### Nuevo Componente

```markdown
[ ] Tipos TypeScript definidos
[ ] Props documentadas
[ ] Estados de loading/error
[ ] Responsive design
[ ] Tests unitarios
```

### Pre-Commit

```markdown
[ ] npm run build exitoso
[ ] npm run lint sin errores
[ ] npm test pasa
[ ] No URLs hardcodeadas
```

---

## PATRONES RECOMENDADOS

### Configuracion de API

```typescript
// src/config/api.ts
const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:3000';

export const apiClient = axios.create({
  baseURL: API_URL,
  timeout: 10000,
});
```

### Componente con Loading/Error

```typescript
function UserList() {
  const { data, isLoading, error } = useQuery('users', fetchUsers);

  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <ul>
      {data.map(user => <UserItem key={user.id} user={user} />)}
    </ul>
  );
}
```

### Variables de Entorno

```bash
# .env.example
VITE_API_URL=http://api.proyecto.localhost
VITE_APP_NAME=Mi App
```

---

## PROHIBICIONES

```yaml
NUNCA:
- Hardcodear URLs de API
- Hardcodear localhost:PORT
- Exponer secrets en codigo
- Crear proyecto sin service.descriptor.yml
- Hacer fetch sin manejo de errores
- Ignorar estados de loading
```

---

## CHANGELOG

### v2.0.0 (2025-12-18)
- Agregado REGISTRY AWARENESS
- Agregado SERVICE DESCRIPTOR WORKFLOW
- Actualizado para Workspace v1

### v1.0.0 (Original)
- Version inicial

---

**Perfil mantenido por:** Tech-Leader
**Ultima actualizacion:** 2025-12-18