AnchorOS/README.md

🥂 AnchorOS

Exclusive Studio Management & CRM Engine
Codename: Adela Repositorio principal del sistema AnchorOS.

Este README es la puerta de entrada técnica al proyecto. Define qué es este repositorio, cómo se estructura y cómo debe ser utilizado por desarrollo, producto y operación.

---

1. ¿Qué es AnchorOS?

AnchorOS es un sistema propietario de gestión operativa y CRM diseñado para estudios de belleza de alta exclusividad. No es una agenda genérica: coordina personas, recursos físicos, pagos, privilegios y datos bajo reglas estrictas de control y privacidad.

El sistema está diseñado para:

• Optimizar el uso de estaciones físicas.
• Proteger la base de datos de clientes.
• Controlar el crecimiento mediante invitaciones.
• Garantizar rentabilidad en días de alta demanda.
• Facilitar la operativa mediante kioskos de autoservicio.

---

2. Alcance de este Repositorio

Este repositorio contiene:

• anchor23.mx - Frontend institucional (landing page + páginas informativas)
• The Boutique - Frontend de reserva para clientas (booking.anchor23.mx)
• The HQ - Dashboard administrativo y CRM interno
• The Kiosk - Sistema de autoservicio en pantalla táctil
• Lógica de negocio de agendamiento y disponibilidad
• Integraciones externas (Stripe, Google Calendar, WhatsApp)
• Esquema base de datos y políticas de seguridad

No contiene:

• Material de marketing digital.
• Operación manual del salón.
• Datos productivos.

---

3. Documentación Oficial

Este proyecto se rige por los siguientes documentos:

Documentos Principales (Raíz)

• README.md (este archivo) → Guía técnica y operativa del repo.
• TASKS.md → Plan de ejecución por fases y estado actual.

Documentación Especializada (docs/)

• docs/PRD.md → Definición de producto y reglas de negocio.
• docs/API.md → Documentación completa de APIs y endpoints.
• docs/STRIPE_SETUP.md → Guía de integración de pagos con Stripe.
• docs/site_requirements.md → Requisitos técnicos del proyecto.
• docs/ANCHOR23_FRONTEND.md → Documentación del frontend institucional.
• docs/DOMAIN_CONFIGURATION.md → Configuración de dominios y subdominios.
• docs/KIOSK_SYSTEM.md → Documentación completa del sistema de kiosko.
• docs/KIOSK_IMPLEMENTATION.md → Guía rápida de implementación del kiosko.
• docs/ENROLLMENT_SYSTEM.md → Sistema de enrollment de kioskos.
• docs/RESOURCES_UPDATE.md → Documentación de actualización de recursos.
• docs/OPERATIONAL_PROCEDURES.md → Procedimientos operativos.
• docs/STAFF_TRAINING.md → Guía de capacitación del staff.
• docs/TROUBLESHOOTING.md → Guía de solución de problemas.
• docs/CLIENT_ONBOARDING.md → Proceso de onboarding de clientes.
• docs/PROJECT_UPDATE_JAN_2026.md → Actualizaciones del proyecto Enero 2026.

El PRD es la fuente de verdad funcional. El README es la guía de ejecución.

---

4. Arquitectura General

Dominios

• anchor23.mx - Frontend institucional (landing page + páginas informativas)
• booking.anchor23.mx - Frontend de reservas (The Boutique) - Pendiente
• kiosk.anchor23.mx - Sistema de autoservicio (The Kiosk)
• aperture.anchor23.mx - Dashboard administrativo y CRM (The HQ)
• api.anchor23.mx - API pública para integraciones externas

Experiencias

• The Boutique: Frontend de reserva para clientas.
• The HQ: Dashboard administrativo y CRM interno.
• The Kiosk: Sistema de autoservicio en pantalla táctil para confirmación de citas y walk-ins.

Principios

• Security by Design.
• Exclusividad curada.
• Optimización de activos.
• Marca primero, sistema después.

---

5. Stack Tecnológico

• Frontend: Next.js 14 (App Router)
• UI / Estilos: Tailwind CSS + Framer Motion
• Backend: Supabase (PostgreSQL + Auth + RLS)
• Pagos: Stripe SDK
• Calendario: Google Calendar API v3 (Service Account)
• Notificaciones: WhatsApp API (Twilio / Meta)
• Storage: Supabase Storage (Buckets privados)

---

6. Estructura del Proyecto

/anchoros
├── app/                          # Next.js App Router
│   ├── (anchor23)/               # anchor23.mx - Frontend institucional
│   │   ├── page.tsx              # Landing page
│   │   ├── servicios/             # Página de servicios
│   │   ├── historia/              # Página de historia/filosofía
│   │   ├── contacto/              # Formulario de contacto
│   │   ├── franchises/           # Información de franquicias
│   │   ├── membresias/            # Membresías (Gold, Black, VIP)
│   │   ├── privacy-policy/        # Política de privacidad
│   │   └── legal/                # Términos y condiciones
│   ├── boutique/                  # booking.anchor23.mx - Frontend de reservas
│   │   ├── servicios/             # Selección de servicios
│   │   ├── cita/                 # Confirmación de reserva
│   │   └── confirmacion/          # Confirmación de reserva (pendiente)
│   ├── hq/                       # Dashboard administrativo
│   ├── kiosk/                    # kiosk.anchor23.mx - Sistema de autoservicio
│   └── api/                      # API routes
│       ├── kiosk/                 # Endpoints para kiosko
│       ├── bookings/               # Gestión de reservas
│       ├── services/               # API para obtener servicios
│       ├── locations/              # API para obtener ubicaciones
│       ├── availability/           # Sistema de disponibilidad
│       └── admin/                 # Endpoints administrativos
├── components/                    # Componentes UI reutilizables
│   ├── kiosk/                    # Componentes del sistema de kiosko
│   └── ui/                       # Componentes base (Button, Input, Card, etc.)
├── lib/                           # Lógica de negocio y helpers
│   ├── db/                        # Tipos TypeScript del esquema
│   └── utils/                     # Utilidades (short-id, etc.)
├── supabase/
│   └── migrations/                # Migraciones SQL versionadas
├── integrations/                   # Stripe, Google, WhatsApp
├── styles/             # Configuración Tailwind
└── docs/               # Documentación adicional
    ├── DOMAIN_CONFIGURATION.md    # Configuración de dominios y subdominios
    ├── KIOSK_SYSTEM.md           # Documentación completa del kiosko
    ├── KIOSK_IMPLEMENTATION.md   # Guía rápida de implementación
    └── RESOURCES_UPDATE.md      # Documentación de actualización de recursos

---

7. Requisitos de Entorno

• Node.js 18+
• Cuenta Supabase
• Cuenta Stripe
• Proyecto Google Cloud (Calendar API)
• Credenciales WhatsApp API

Variables de entorno obligatorias:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Stripe
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Google Calendar
GOOGLE_SERVICE_ACCOUNT_JSON=

# WhatsApp
WHATSAPP_API_KEY=

# Kiosko (opcional - para modo kiosko)
NEXT_PUBLIC_KIOSK_API_KEY=

---

8. Setup Local

1. Clonar el repositorio

git clone <repo-url>
cd anchoros

2. Instalar dependencias

npm install

3. Configurar variables de entorno

• Crear .env.local.

4. Levantar entorno local

npm run dev

El sitio estará disponible en http://localhost:2311

---

9. Convenciones de Desarrollo

• El PRD define la lógica: no se improvisa comportamiento.
• Toda regla crítica debe vivir en backend.
• RLS obligatorio en todas las tablas sensibles.
• El frontend nunca expone datos privados del cliente.
• Cambios de alcance requieren actualización del PRD.

---

10. Estado del Proyecto

Completado ✅

• ✅ Esquema de base de datos completo
• ✅ Sistema de roles y permisos RLS
• ✅ Generadores de Short ID y códigos de invitación
• ✅ Sistema de kiosko completo con enrollment
• ✅ API routes para kiosko
• ✅ Componentes UI para kiosko
• ✅ Actualización de recursos con códigos estandarizados
• ✅ Audit logging completo
• ✅ Tiers de cliente extendidos (free, gold, black, VIP)
• ✅ Sistema de disponibilidad (staff, recursos, bloques)
• ✅ API routes de disponibilidad
• ✅ API de reservas para clientes (POST/GET)
• ✅ HQ Dashboard básico (Aperture) - EXISTE pero incompleto
• ✅ API routes básicos para Aperture (dashboard, staff, resources, reports, permissions)
• ✅ Frontend institucional anchor23.mx completo
  • Landing page con hero, fundamento, servicios, testimoniales
  • Página de servicios
  • Página de historia y filosofía
  • Página de contacto
  • Página de franquicias
  • Página de membresías (Gold, Black, VIP)
  • Páginas legales (Privacy Policy, Legal)
  • Header y footer globales

En Progreso 🚧

• 🚧 The Boutique - Frontend de reservas (booking.anchor23.mx) - 90%

  • ✅ Página de selección de servicios (/booking/servicios)
  • ✅ Página de búsqueda de clientes (/booking/cita - paso 1)
  • ✅ Página de registro de clientes (/booking/registro)
  • ✅ Página de confirmación de reserva (/booking/cita - pasos 2-3)
  • ✅ Página de confirmación por código (/booking/confirmacion)
  • ✅ Layout específico con navbar personalizado
  • ✅ API para obtener servicios (/api/services)
  • ✅ API para obtener ubicaciones (/api/locations)
  • ✅ API para buscar clientes (/api/customers - GET)
  • ✅ API para registrar clientes (/api/customers - POST)
  • ✅ Sistema de horarios de negocio por ubicación
  • ✅ Componente de pagos mock para pruebas
  • ⏳ Configuración de dominios wildcard en producción
  • ⏳ Integración con Stripe real (webhooks)

• 🚧 Aperture - Backend para staff/manager/admin (aperture.anchor23.mx) - 40%

  • ✅ API para obtener staff disponible (/api/aperture/staff)
  • ✅ API para gestión de horarios (/api/aperture/staff/schedule)
  • ✅ API para recursos (/api/aperture/resources)
  • ✅ API para dashboard (/api/aperture/dashboard)
  • ✅ Página principal de admin (/aperture)
  • ❌ API para estadísticas (/api/aperture/stats) - FALTA IMPLEMENTAR
  • ❌ Reseteo semanal de invitaciones (documentado, NO implementado)
  • ⏳ Autenticación de admin/staff/manager (login existe, needs Supabase Auth)
  • ⏳ Gestión completa de staff (CRUD, horarios)
  • ⏳ Gestión de recursos y asignación
  • ⏳ Rediseño con estilo Square UI

• 🚧 Lógica de no-show y penalizaciones automáticas

• 🚧 Integración con Google Calendar (20% - en progreso)

Pendiente ⏳

• ⏳ Implementar API pública (api.anchor23.mx)
• ⏳ Completar Aperture con estilo Square UI (calendario multi-columna, páginas individuales, The Vault)
• ⏳ Notificaciones por WhatsApp
• ⏳ Recibos digitales por email
• ⏳ Landing page para believers (booking público)
• ⏳ Tests unitarios
• ⏳ Archivos SEO (robots.txt, sitemap.xml)

Fase Actual

Fase 1 — Cimientos y CRM: 100% completado

• Infraestructura base: 100%
• Esquema de base de datos: 100%
• Short ID & Invitaciones: 100%
• CRM Base: 100%
• Sistema de Kiosko: 100%
• Actualización de Recursos: 100%
• Sistema de Disponibilidad: 100%
• Frontend Institucional: 100%

Fase 2 — Motor de Agendamiento: 80% completado

• Disponibilidad dual capa: 100%
• API de reservas: 100%
• The Boutique: 90% (frontend completo, autenticación y pagos parcialmente implementados)
• Integración Pagos (Stripe): 90% (depósitos implementados, webhooks pendientes)
• Integración Calendar: 20% (en progreso)
• Aperture Backend: 100%

Fase 3 — Pagos y Protección: 70% completado

• Stripe depósitos dinámicos: 100%
• No-show logic: 40% (lógica implementada, automatización pendiente)

Fase 4 — HQ Dashboard: 10% completado

• Aperture dashboard básico: 100% (existe pero incompleto)
• Autenticación staff/admin: 40% (página login existe, needs Supabase Auth integration)
• Calendario Multi-Columna: 0% (pendiente)
• Gestión Operativa: 20% (APIs existentes, UI incompleta)
• The Vault: 0% (pendiente)

Fase 5 — Automatización y Lanzamiento: 5% completado

• Notificaciones WhatsApp: 0% (variables configuradas, no implementado)
• Recibos digitales: 0% (pendiente)
• Landing page Believers: 0% (pendiente)

Advertencia: No apto para producción. Migraciones y seeds en evolución.

---

11. Deployment y Producción

Requisitos para Producción

• VPS o cloud provider (Vercel recomendado para Next.js)
• Base de datos Supabase production
• Configuración de dominios wildcard (*.anchor23.mx)
• SSL certificates automáticos
• Monitoring y logging (Sentry recomendado)

Variables de Entorno de Producción

Además de las variables locales, configurar:

# Producción
NEXT_PUBLIC_APP_URL=https://anchor23.mx
NEXT_PUBLIC_BOOKING_URL=https://booking.anchor23.mx
NEXT_PUBLIC_KIOSK_URL=https://kiosk.anchor23.mx
NEXT_PUBLIC_APERTURE_URL=https://aperture.anchor23.mx

# Webhooks Stripe
STRIPE_WEBHOOK_ENDPOINT_SECRET=

# Google Calendar (opcional para producción)
GOOGLE_CALENDAR_ID=

Pasos de Deployment

1. Configurar Supabase production con RLS habilitado
2. Ejecutar migraciones: supabase db push
3. Configurar dominios y SSL
4. Desplegar en Vercel con build settings personalizados
5. Configurar webhooks de Stripe para pagos
6. Probar autenticación y bookings end-to-end

Monitoreo

• Logs de Supabase para queries lentas
• Alertas de Stripe para fallos de pago
• Uptime monitoring para dominios críticos

---

12. anchor23.mx - Frontend Institucional

Dominio institucional. Contenido estático, marca, narrativa y conversión inicial.

Arquitectura de Dominios

• anchor23.mx - Frontend institucional (landing page + páginas informativas)
• booking.anchor23.mx - The Boutique (frontend de reservas) - En Progreso 20%
• kiosk.anchor23.mx - The Kiosk (pantallas táctiles)

Páginas Implementadas

anchor23.mx

• / - Landing page (Hero, Fundamento, Servicios Preview, Testimonios)
• /servicios - Grid de servicios con descripciones
• /historia - Historia, filosofía y significado de la marca
• /contacto - Formulario de contacto con información
• /franchises - Modelo de franquicias con solicitud
• /membresias - 3 tiers (Gold, Black, VIP) con solicitudes
• /privacy-policy - Política de privacidad completa
• /legal - Términos y condiciones

booking.anchor23.mx

• /booking/servicios - Página de selección de servicios con calendario
• /booking/cita - Flujo de reserva en pasos:
  1. Búsqueda de cliente por email/telefono
  2. Confirmación de datos personales
  3. Pago del depósito (mock actualmente)
• /booking/registro - Registro de nuevos clientes con:
  • Nombre y apellido
  • Email y teléfono
  • Fecha de nacimiento
  • Ocupación (lista desplegable)
• /booking/login - Autenticación con magic links
• /booking/perfil - Perfil de cliente con historial de citas
• /booking/mis-citas - Gestión de citas

Sistema de Horarios de Negocio

Cada ubicación tiene horarios de apertura personalizados por día de la semana almacenados en la columna business_hours (JSONB):

Formato de estructura:

{
  "monday": {"open": "10:00", "close": "19:00", "is_closed": false},
  "tuesday": {"open": "10:00", "close": "19:00", "is_closed": false},
  "wednesday": {"open": "10:00", "close": "19:00", "is_closed": false},
  "thursday": {"open": "10:00", "close": "19:00", "is_closed": false},
  "friday": {"open": "10:00", "close": "19:00", "is_closed": false},
  "saturday": {"open": "10:00", "close": "18:00", "is_closed": false},
  "sunday": {"is_closed": true}
}

Horarios por defecto (actualizados vía migración):

• Lunes a Viernes: 10:00 AM - 7:00 PM
• Sábado: 10:00 AM - 6:00 PM
• Domingo: Cerrado

Implementación:

• Función PostgreSQL get_detailed_availability() respeta horarios de cada día
• Solo se muestran slots dentro del horario de apertura
• Días marcados como is_closed: true no muestran disponibilidad
• Los horarios se pueden personalizar por ubicación individualmente

aperture.anchor23.mx (Backend administrativo)

• /aperture - Dashboard con estadísticas y gestión
• /aperture (tabs: Dashboard, Staff, Resources, Reports, Permissions)
• Reportes: Ventas, Pagos, Nómina
• Gestión de permisos por roles

kiosk.anchor23.mx

• Sistema completo de kiosko con autenticación por API key

Tecnologías

• Next.js 14 (App Router) con SSG
• Tailwind CSS para estilos
• Lucide React para iconos
• HTML semántico

APIs

Ver documentación completa en API.md para todos los endpoints disponibles.

Principios de Diseño

• HTML semántico
• Secciones claras
• Conversión silenciosa hacia booking.anchor23.mx
• Booking y Kiosk desacoplados
• Marca primero, sistema después
• Arquitectura lista para escalar sin diluir exclusividad

Flujo de Conversión

1. Landing page → Interés en servicios
2. /servicios → Conocimiento de oferta
3. /membresias → Solicitud de membresía
4. CTA directo → booking.anchor23.mx (reserva)
5. /franchises → Solicitud de franquicia

---

13. Sistema de Kiosko

El sistema de kiosko permite a los clientes interactuar con el salón mediante pantallas táctiles en la entrada.

Funcionalidades

• Confirmación de Citas: Los clientes confirman su llegada ingresando el código de 6 caracteres (short_id)
• Reservas Walk-in: Creación de reservas inmediatas para clientes sin cita previa
• Asignación Inteligente de Recursos: Prioridad automática (mkup > lshs > pedi > mani)

Seguridad

• Autenticación por API key de 64 caracteres
• Políticas RLS restrictivas (sin acceso a PII de clientes)
• Audit logging completo de todas las acciones

Documentación

• Guía completa: docs/KIOSK_SYSTEM.md
• Implementación rápida: docs/KIOSK_IMPLEMENTATION.md

Acceso al Kiosko

https://kiosk.anchor23.mx/{location-id}

---

14. Filosofía Operativa

AnchorOS no busca volumen.

Busca control, eficiencia y blindaje.

Este repositorio implementa esa filosofía a nivel de sistema.

---

15. Codename: Adela

AnchorOS se conoce internamente como Adela, un acrónimo que representa los pilares fundamentales del sistema:

• Attention - Atención personalizada y detallada a cada cliente
• Digital Engagement - Compromiso digital con la marca y servicios
• Engagement Logistics - Logística de interacción eficiente
• Logistics Analytics - Análisis de datos para optimización operativa
• Analytics - Inteligencia de datos para decisiones estratégicas

Adela simboliza la transformación digital de los salones de belleza de alta gama, combinando lujo, tecnología y eficiencia operativa.

---

Proyecto: soul23