michangarrito/CLAUDE.md

# CLAUDE.md - MiChangarrito

**Hereda de:** workspace-v2/CLAUDE.md, template-saas
**Sistema:** SIMCO v4.3.0 + NEXUS v4.0
**Proyecto:** michangarrito
**Tipo:** CONSUMER (de template-saas)
**Versión:** 1.0.0
**Actualizado:** 2026-02-06
**ADR Vinculante:** ADR-0011 (Estructura Canonica apps/)

---

## EXTENSIONES LOCALES

Este archivo EXTIENDE (no reemplaza) las reglas del workspace.
Para reglas base, ver: `../../CLAUDE.md`

---

## DESCRIPCION DEL PROYECTO

MiChangarrito es un SaaS para tienditas/changarros mexicanos con:
- Punto de Venta (POS) móvil y web
- Gestión de inventario inteligente
- Integración WhatsApp Business
- Pagos múltiples (Stripe, MercadoPago, CoDi, SPEI)
- Asistente IA para comerciantes

---

## STACK TECNOLOGICO

| Capa | Tecnología | Versión |
|------|------------|---------|
| Backend | NestJS | 10.3.0 |
| Frontend Web | React + Vite | 19.2.0 |
| Mobile | React Native (Expo) | SDK 51 |
| Database | PostgreSQL | 16+ |
| Cache | Redis | 7 |
| ORM | TypeORM | 0.3.x |
| WhatsApp | Meta Business API | - |
| LLM | OpenRouter/Claude/GPT-4 | Multi-provider |

---

## CREDENCIALES BD

```
Database: michangarrito_dev
User: michangarrito_dev
Password: mch_dev_2026
Port: 5432
Host: localhost
Redis Port: 6389
```

---

## ESTRUCTURA CANONICA (ADR-0011)

```
michangarrito/
├── apps/                          # Contenedor canonico de aplicaciones
│   ├── backend/                   # NestJS API (submodule, 23 modulos)
│   ├── frontend-web/              # React Web App (submodule)
│   ├── frontend-mobile/           # React Native Expo (submodule)
│   ├── mcp-server/                # Gateway LLM (submodule, 15 herramientas)
│   ├── whatsapp-service/          # Meta Cloud API (submodule)
│   ├── database/                  # DDL PostgreSQL (submodule, 11 schemas)
│   └── _MAP.md                    # Indice de aplicaciones
├── orchestration/                 # Sistema SIMCO local
├── docs/                          # Documentacion
├── .claude/                       # Instrucciones Claude Code
└── .gitmodules                    # 6 submodules en apps/
```

**IMPORTANTE:** Todo desarrollo nuevo DEBE ir dentro de `apps/`. No crear archivos en raiz.

---

## MODULOS BACKEND (23)

| Módulo | Descripción |
|--------|-------------|
| auth | JWT + OTP + PIN + Biométrico |
| billing | Suscripciones |
| categories | Catálogos |
| codi-spei | Pagos QR Banxico |
| customers | Clientes + Fiados |
| delivery | Entregas domicilio |
| exports | Exportación datos |
| integrations | Integraciones |
| inventory | Control inventario |
| invoices | Facturación |
| marketplace | Marketplace B2B |
| messaging | Mensajería |
| notifications | Push/Email/WhatsApp |
| onboarding | Onboarding inteligente |
| orders | Pedidos |
| payments | Gateway pagos |
| products | Catálogo productos |
| referrals | Programa referidos |
| sales | Punto de venta |
| settings | Configuración |
| subscriptions | Planes suscripción |
| templates | Templates catálogos |
| widgets | Widgets/Atajos |

---

## PUERTOS DE SERVICIOS

| Servicio | Puerto |
|----------|--------|
| Backend API | 3141 |
| Frontend Web | 3140 |
| Mobile (Expo) | 8081 |
| MCP Server | 3142 |
| WhatsApp Service | 3143 |
| PostgreSQL | 5432 |
| Redis | 6389 |

---

## HERENCIA

### Este proyecto hereda de:
- `workspace-v2/orchestration/` → Directivas globales
- `template-saas/` → Patrones SaaS, multi-tenancy, auth

### NO exporta a otros proyectos
- Es aplicación final (CONSUMER)

---

## REGLAS ESPECIFICAS

### 1. Multi-Tenancy

- Cada changarrito es un tenant
- RLS obligatorio en queries
- Datos completamente aislados

### 2. Pagos México

- CoDi/SPEI: Validar con Banxico sandbox
- MercadoPago: Usar cuenta de pruebas
- Clip: Solo modo sandbox

### 3. WhatsApp Business

- Meta Cloud API únicamente
- Validar templates antes de enviar
- Rate limits estrictos

### 4. LLM Integration

- MCP Server agnóstico a proveedor
- OpenRouter como fallback
- Caché de respuestas para costos

---

## VALIDACIONES ADICIONALES

Además de las validaciones del workspace:

1. **Backend:**
   ```bash
   cd apps/backend && npm run build && npm run lint
   ```

2. **Frontend:**
   ```bash
   cd apps/frontend-web && npm run build && npm run lint
   ```

3. **Mobile:**
   ```bash
   cd apps/frontend-mobile && npx expo doctor
   ```

---

## ALIASES LOCALES

- `@BACKEND` → apps/backend/src/modules/
- `@FRONTEND` → apps/frontend-web/src/
- `@MOBILE` → apps/frontend-mobile/src/
- `@WHATSAPP` → apps/whatsapp-service/
- `@MCP` → apps/mcp-server/
- `@DDL` → apps/database/

---

## ANTES DE IMPLEMENTAR

1. Verificar especificación en `docs/`
2. Consultar si ya existe en `template-saas`
3. Revisar herencia - NO duplicar lo heredado
4. Considerar impacto en móvil Y web

---

## DESPUES DE IMPLEMENTAR

1. Actualizar inventarios locales
2. Verificar que funciona en web Y móvil
3. Commit y push siguiendo SIMCO-GIT
4. **NO propagar** - es CONSUMER

---

## ESTADO ACTUAL

```yaml
Madurez: Pre-producción
MVP: 95% completado
En Producción: No
Modo: Multi-tenant

Bloqueadores para Producción:
  - Cuenta Meta Business verificada
  - API keys Stripe producción
  - API keys LLM producción
```

---

- `@APPS-MAP` → apps/_MAP.md

---

*MiChangarrito v1.0.0 - Sistema SIMCO v4.0.0*
*Estructura migrada a apps/ canonico: 2026-02-06*