# Especificación de Componentes - MiChangarrito

**Última actualización**: 2026-01-05

---

## Resumen de Componentes

| Componente | Puerto | Framework | Estado |
|------------|--------|-----------|--------|
| Frontend Web | 3140 | React 18 + Vite | Implementado |
| Backend API | 3141 | NestJS 10.x | Implementado |
| MCP Server | stdio | MCP SDK | Implementado |
| WhatsApp Service | 3143 | NestJS 10.x | Implementado |
| Mobile App | 8081 | React Native | Pendiente |

---

## Backend API

### Ubicación
`apps/backend/`

### Módulos

| Módulo | Descripción | Endpoints Base |
|--------|-------------|----------------|
| AuthModule | Autenticación JWT | `/auth/*` |
| UsersModule | Gestión de usuarios | `/users/*` |
| ProductsModule | CRUD productos | `/products/*` |
| SalesModule | Punto de venta | `/sales/*` |
| CustomersModule | Clientes y fiado | `/customers/*` |
| InventoryModule | Stock y movimientos | `/inventory/*` |
| OrdersModule | Pedidos WhatsApp | `/orders/*` |
| SubscriptionsModule | Planes y tokens | `/subscriptions/*` |
| MessagingModule | Conversaciones | `/messaging/*` |

### Ejecución
```bash
cd apps/backend
npm run start:dev    # Desarrollo
npm run build        # Producción
```

---

## WhatsApp Service

### Ubicación
`apps/whatsapp-service/`

### Capacidades
- Envío de mensajes texto
- Mensajes interactivos (botones, listas)
- Templates de WhatsApp
- Recepción via webhook
- Procesamiento LLM

### Webhook
```
GET  /webhook/whatsapp  # Verificación Meta
POST /webhook/whatsapp  # Recepción de mensajes
```

### Ejecución
```bash
cd apps/whatsapp-service
npm run start:dev
```

---

## MCP Server

### Ubicación
`apps/mcp-server/`

### Herramientas Disponibles

**Productos:**
- `list_products` - Listar productos
- `get_product_details` - Detalles de producto
- `check_product_availability` - Verificar stock

**Pedidos:**
- `create_order` - Crear pedido
- `get_order_status` - Estado de pedido
- `update_order_status` - Actualizar estado
- `cancel_order` - Cancelar pedido

**Fiado:**
- `get_fiado_balance` - Saldo de cliente
- `create_fiado` - Registrar fiado
- `register_fiado_payment` - Registrar pago
- `get_fiado_history` - Historial
- `check_fiado_eligibility` - Verificar elegibilidad

**Clientes:**
- `get_customer_info` - Info de cliente
- `register_customer` - Registrar cliente
- `get_customer_purchase_history` - Historial compras
- `get_customer_stats` - Estadísticas

**Inventario:**
- `check_stock` - Verificar stock
- `get_low_stock_products` - Productos con stock bajo
- `record_inventory_movement` - Registrar movimiento
- `get_inventory_value` - Valor del inventario

### Ejecución
```bash
cd apps/mcp-server
npm run build
npm start
```

---

## Frontend Web

### Ubicación
`apps/frontend/`

### Stack
- React 18
- Vite 7.x
- TailwindCSS 4.x
- React Router 6
- TanStack Query

### Páginas

| Ruta | Página | Descripción |
|------|--------|-------------|
| `/dashboard` | Dashboard | Resumen y estadísticas |
| `/products` | Products | Catálogo de productos |
| `/orders` | Orders | Gestión de pedidos |
| `/customers` | Customers | Lista de clientes |
| `/fiado` | Fiado | Gestión de crédito |
| `/inventory` | Inventory | Control de stock |
| `/settings` | Settings | Configuración |

### Ejecución
```bash
cd apps/frontend
npm run dev      # Desarrollo
npm run build    # Producción
```

---

## Configuración de Entorno

Variables requeridas en `.env`:

```env
# Base de datos
DB_HOST=localhost
DB_PORT=5432
DB_NAME=michangarrito_dev
DB_USER=michangarrito_dev
DB_PASSWORD=MCh_dev_2025_secure

# JWT
JWT_SECRET=<secret>

# WhatsApp
WHATSAPP_ACCESS_TOKEN=<token>
WHATSAPP_PHONE_NUMBER_ID=<id>
WHATSAPP_VERIFY_TOKEN=<token>

# LLM
OPENAI_API_KEY=<key>
LLM_MODEL=gpt-4o-mini
```

---

## Referencias

- [Arquitectura Database](./ARQUITECTURA-DATABASE.md)
- [Environment Inventory](../../orchestration/environment/ENVIRONMENT-INVENTORY.yml)