02 — Estructura de carpetas

Vista de alto nivel

chatbot-v3-workspace/
├── backend_django/         ← Backend único (Django 4.2 + DRF + JWT + Stripe)
├── apps/
│   ├── dashboard/          ← Frontend cliente (React + Vite + Tailwind)
│   └── superadmin/         ← Frontend superadmin (React + Vite + Tailwind)
├── static/
│   └── v3/                 ← Widget embebible (loader + frame + bundle dist/)
├── infra/                  ← Configs de referencia (NO usar tal cual; ver .saas-docs/infra)
├── test/                   ← Suite de smoke tests (pytest + curl)
├── .saas-docs/             ← Este manual
├── .env.example            ← Plantilla de variables de entorno
├── .env                    ← (Real, NO commitear) creado por el operador
└── .gitignore

backend_django/

backend_django/
├── manage.py               ← Entry point Django
├── requirements.txt        ← Deps Python (~15 paquetes, todos pinned)
├── pytest.ini              ← Config de tests
├── conftest.py             ← Fixtures globales pytest
├── venv/                   ← Virtualenv (NO commitear)
├── media/                  ← Uploads de usuario (logos, avatares)
├── staticfiles/            ← Output de `manage.py collectstatic`
│
├── blimx_admin/            ← Project root (settings, urls, wsgi)
│   ├── settings.py         ← INSTALLED_APPS, MIDDLEWARE, DB, JWT, STRIPE, STATIC
│   ├── urls.py             ← Routes de alto nivel: /api/, /api/auth/, /v3/, /admin/
│   ├── wsgi.py             ← Entry de gunicorn
│   └── asgi.py             ← (no se usa; no hay async)
│
├── api/                    ← App principal de la API
│   ├── models.py           ← Account, Bot, Plan, Subscription, KB, Invoice, etc.
│   ├── serializers.py      ← DRF serializers
│   ├── views.py            ← DashboardViewSet (orquesta /api/client/...)
│   ├── views_accounts.py   ← Endpoints de Account (gestión de la cuenta)
│   ├── views_billing.py    ← Stripe checkout, portal, plan switching
│   ├── views_bot_users.py  ← Invitar usuarios a un bot, permisos
│   ├── views_bots_mixin.py ← CRUD de bots
│   ├── views_config_mixin.py ← Configuración del widget por bot
│   ├── views_faqs_mixin.py ← CRUD de FAQs y categorías
│   ├── views_onboarding.py ← Flow de onboarding (crear primer bot)
│   ├── views_plans.py      ← GET /api/client/plans/ (listar planes)
│   ├── views_profiles.py   ← Perfiles de bot (templates de configuración)
│   ├── views_saas_users.py ← Usuarios del SaaS (invitaciones, perfiles)
│   ├── views_stripe_webhook.py ← Webhook Stripe (firma + sincronización)
│   ├── views_superadmin.py ← Endpoints /api/sa/* (panel superadmin)
│   ├── widget/             ← Endpoints públicos del chatbot embebido
│   │   ├── views.py        ← /v3/health, /v3/frontend/config, /v3/faq
│   │   ├── services.py     ← Queries DB para el widget
│   │   ├── urls.py
│   │   └── README.md       ← Doc específica de la sub-app
│   ├── services/           ← Lógica de negocio reutilizable
│   │   ├── plan_policy_engine.py ← Limits de plan (FAQs, idiomas, branding)
│   │   ├── invoice_service.py    ← Generación de facturas PDF
│   │   └── ...
│   ├── stripe_utils.py     ← Helpers para Stripe
│   ├── upload_validation.py ← Validación de logos/avatares
│   ├── middleware.py       ← RequestId, BuildInfo, audit
│   ├── management/
│   │   └── commands/       ← `manage.py <comando>` custom
│   ├── migrations/         ← Migraciones Django
│   └── tests/              ← Unit + integration tests
│
├── authentication/         ← App de auth (separada para aislar)
│   ├── models.py           ← SaasUser, AccountUser, PrelaunchCode
│   ├── jwt_auth.py         ← Autenticación JWT custom (multi-realm)
│   ├── views.py            ← register, login, refresh, password reset
│   ├── views_invitation_admin.py  ← Invitar desde superadmin
│   ├── views_invitation_public.py ← Aceptar invitación
│   ├── permissions.py      ← IsAccountOwner, IsBotMember, IsSaasUser
│   ├── serializers.py
│   ├── urls.py
│   └── tests.py
│
└── scripts/                ← Scripts auxiliares (seeders, migraciones manuales)

apps/dashboard/

Frontend cliente (lo que ve el comprador del SaaS y los usuarios que invita).

apps/dashboard/
├── package.json            ← Deps npm (React 18, Vite 5, axios, i18next, lucide-react)
├── vite.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── index.html              ← Entry de Vite
├── public/                 ← Assets estáticos copiados al build
└── src/
    ├── main.tsx            ← React DOM render
    ├── ClientDashboardApp.tsx ← Router + providers
    ├── api/                ← Cliente HTTP (axios instances)
    ├── auth/               ← Context de auth, JWT manager
    ├── components/         ← Componentes compartidos
    ├── pages/              ← Páginas: OverviewPage, BotConfigurationPage, BillingPage, etc.
    ├── pages/bots/         ← Pages bajo /bots/<slug>/...
    ├── layouts/            ← DashboardLayout (sidebar + topbar)
    ├── hooks/              ← Custom hooks
    ├── i18n/               ← Setup i18next + locales JSON
    │   └── locales/
    │       ├── es.json
    │       ├── en.json
    │       ├── fr.json
    │       ├── de.json
    │       └── pt.json
    ├── lib/                ← Helpers (apiBase, formatters)
    └── types/              ← TypeScript types compartidos

apps/superadmin/

Frontend de operación de la plataforma (lo usa el comprador del SaaS para administrar todos los Accounts).

apps/superadmin/
├── package.json
├── vite.config.ts
├── src/
│   ├── modules/superadmin/
│   │   ├── pages/          ← TenantsListPage, TenantDetailPage, PlansPage, etc.
│   │   └── api/            ← Cliente HTTP a /api/sa/*
│   ├── components/
│   └── i18n/locales/

static/v3/

Widget embebible que el cliente final pega en su web (<script src=".../blimx-v3-chatbot-loader.js">).

static/v3/
├── blimx-v3-chatbot-loader.js     ← (Source) Lo que se incluye en la web del cliente
├── blimx-v3-chatbot-frame.html    ← (Source) HTML del iframe
├── build.js                       ← Script de build con Vite (genera dist/)
├── package.json                   ← Deps de build (vite, terser)
├── vite.config.js
├── i18n/                          ← Strings del widget (JSON por idioma)
├── css2/
│   └── main.css                   ← CSS source del widget
├── js2/                           ← Source modular del widget
│   ├── chatbot.js                 ← Orquestador (entry para Vite)
│   ├── core/
│   │   ├── ApiService.js          ← Llamadas a /v3/frontend/config y /v3/faq
│   │   ├── StateManager.js
│   │   ├── UIManager.js
│   │   ├── LanguageManager.js
│   │   └── Telemetry.js
│   └── components/
│       ├── Launcher.js            ← Botón flotante
│       ├── Modal.js               ← Contenedor del modal
│       ├── HeaderView.js
│       ├── NavbarView.js
│       └── FaqView.js             ← Vista de FAQs (la única activa)
├── img/                           ← Iconos del widget
└── dist/                          ← Output del build (servido por nginx)
    ├── blimx-chatbot.min.js       ← Bundle JS (~24 KB)
    ├── blimx-chatbot.min.css      ← CSS minificado
    └── blimx-v3-chatbot-frame.html ← Frame con paths relativos a /static/v3/dist/

Detalle completo del widget en 13-widget-embebido.md.

Carpetas que NO van en el zip de entrega

Carpeta	Por qué excluirla
backend_django/venv/	Cada servidor crea el suyo
backend_django/staticfiles/	Output de collectstatic, se regenera
backend_django/media/	Uploads de usuario, específicos del entorno
backend_django/__pycache__/	Caché Python
apps/*/node_modules/	npm install lo regenera
apps/*/dist/	Output de npm run build, se regenera
static/v3/node_modules/	Idem
static/v3/dist/	Output de node build.js, se regenera
.env	Secretos del operador
.saas-docs.bak.*/	Backups de iteraciones del manual

Todas están en .gitignore. El zip de entrega se genera con git archive HEAD.