┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│  Panel Web   │────▶│  SurveysModule   │────▶│  Supabase    │
│  (Admin)     │     │  (NestJS)        │     │  (PostgreSQL)│
└──────────────┘     └──────────────────┘     └──────────────┘
                            │
┌──────────────┐            │            ┌──────────────┐
│ vivla-mobile │────────────┘            │  Firestore   │
│ (responses)  │     surveys/mobile/*    │  (legacy)    │
└──────────────┘                         └──────────────┘
                            │
┌──────────────┐            │
│  Windmill    │────────────┘
│  (cron 1h)   │  POST /chat/sync/firebase-legacy-responses
└──────────────┘

apps/backend/src/surveys/
  surveys.module.ts
  surveys.controller.ts             # CRUD survey types + surveys (admin)
  surveys.service.ts                # CRUD + publishing + i18n resolution
  mobile/
    mobile.controller.ts            # GET definition, POST responses, complete, resume
    dto/mobile-submit-response.dto.ts
  responses/
    responses.service.ts            # Upsert parcial, complete con inmutabilidad
  results/
    results.controller.ts           # Resultados agregados + CSV export (enriched)
    results.service.ts              # Aggregation por tipo de pregunta + CSV con nombres resueltos
    legacy-results.controller.ts    # Resultados legacy desde Firestore
    legacy-results.service.ts       # Lee de Firestore (nps-home-responses, etc.)
    legacy-responses-query.controller.ts  # Per-user/per-property tables from survey_legacy_responses
    legacy-responses-query.service.ts     # Typed queries: stay, arrival, onboarding, financial, home-review + PG score extraction
  scores/
    score-summary.service.ts        # Pre-computed scores: recompute, query, user matrix (multi-source)
    score-summary.controller.ts     # GET /survey-scores, /user-matrix, /summary, /analytics
    home-review-results.service.ts  # Custom home-review results with consensus
  rewards/
    rewards.controller.ts           # Rewards mobile endpoints
    rewards.service.ts              # Auto-award on complete, niveles, ciclo reset
  action-plans/
    action-plans.controller.ts      # CRUD + generate
    action-plans.service.ts         # Generate desde consenso, approve/send
    consensus.service.ts            # Configurable thresholds from result_config
  public/
    public-results.controller.ts    # Public endpoints for home-excellence app
  dto/                              # DTOs de validación
  entities/                         # Entities (survey-type, survey, response)
  types/
    survey.types.ts                 # Contratos TypeScript completos

# Sync module (chat/sync/) — extended for surveys
  sync.controller.ts                # POST /chat/sync/firebase-legacy-responses (+ users, properties, deals, bookings)
  sync.service.ts                   # triggerSyncFirebaseLegacyResponses() — spawns CLI as child process

# CLI scripts
  cli/
    sync-firebase-legacy-responses.ts  # Individual response migration (--dry-run, --report-only)
    sync-firebase-scores.ts            # Aggregated scores migration

# Migrations (schema + seeds)
  database/migrations/
    050_create_surveys_tables.sql       # Core schema + seed 3 survey types
    054_seed_home_review.sql            # Home Review v1 (active) + v2 (draft) with cleanup
    058_create_survey_legacy_responses.sql  # Legacy responses table + onboarding-review type
    059_seed_financial_review.sql       # Financial-review type + 42 CSV legacy responses

apps/frontend/app/routes/app.chat/
  surveys.tsx                       # Layout: SurveysSubNav + <Outlet />
  surveys.index.tsx                 # Actividad (response log, quick actions)
  surveys.admin.tsx                 # Layout: <Outlet />
  surveys.admin.index.tsx           # Lista tipos por scope
  surveys.admin.$surveyTypeId.edit.$surveyId.tsx  # Builder
  surveys.results.tsx               # Resultados + legacy viewer
  surveys.action-plans.tsx          # Action plans list + detail
  surveys.rewards.tsx               # Rewards (bar chart + nivel 5 config)

apps/frontend/app/components/chat/surveys/
  SurveysActivityPage.tsx           # Response log, inline link builder, filtros, CSV export enriquecido
  SurveysSubNav.tsx                 # Sub-nav de 5 items
  SurveysAdminPage.tsx              # Tipos por scope en 2 columnas
  SurveysRewardsPage.tsx            # Gráfico de barras por nivel
  DeepLinkGeneratorModal.tsx        # Generador inline de deep links
  NpsScoreBadge.tsx                 # Badge de puntuación NPS (escala cromática 11 colores)
  builder/
    SurveyBuilder.tsx               # Builder completo con i18n tabs
    StepEditor.tsx                  # Editor de steps
    QuestionEditor.tsx              # 5 tipos, display_style, allow_audio
    ConditionalEditor.tsx           # Conditionals múltiples con hijas
    SurveyPreview.tsx               # Preview en vivo
  results/
    ResultsListPage.tsx             # URL-navigable tabs + sub-tabs, version selector,
                                    # typed tables (user/property columns with avatars),
                                    # expandable property rows, CSV export (green button),
                                    # LegacyDashboardContent, LegacyResponsesSubTab,
                                    # UserStatusTab (multi-source, date-filtered)
    SurveyResultsPage.tsx           # Averages, distributions, CSV export (backend enriched)
  action-plans/
    ActionPlansPage.tsx             # Lista + detalle + approve/send

apps/frontend/app/lib/surveys/surveys-api.ts   # Métodos API
apps/frontend/app/types/surveys.ts              # Tipos TypeScript frontend

{
  "negative_threshold": 4,
  "participation_threshold": 0.75,
  "consensus_threshold": 0.75,
  "min_owners_for_plan": 4
}

NpsScoreBadge.tsx
  Props: value (0-5), size ('sm' | 'md')
  sm: 32×32px (tablas, inline)
  md: 40×40px (cards dashboard, héroes)

# Desde apps/backend/
pnpm sync:firebase-legacy-responses              # Migra respuestas individuales
pnpm sync:firebase-legacy-responses --dry-run     # Preview sin escribir
pnpm sync:firebase-legacy-responses --report-only # Solo genera reporte diagnóstico (JSON + MD)
pnpm sync:firebase-legacy-responses --collection=nps-booking  # Solo una colección

# Desde apps/backend/
pnpm sync:firebase-scores          # Sincroniza scores agregados → survey_score_summaries
pnpm sync:firebase-scores --dry-run # Preview sin escribir

Home Excellence (Next.js 14, port 3003)
  └─ /api/surveys/* (rewrite)
       └─ Backend (NestJS, port 3001)
            ├─ PublicResultsController
            │   ├─ ResultsService (agregación desde PostgreSQL)
            │   ├─ LegacyResultsService (lectura Firestore)
            │   └─ ActionPlansService (planes por scope)
            └─ ScoreSummaryController
                └─ HomeReviewResultsService (consenso, participación)