template-saas/orchestration/00-guidelines/CONTEXTO-PROYECTO.md

CONTEXTO: Template SaaS

Proyecto: template-saas Descripcion: Template base para plataformas SaaS multi-tenant Fecha creacion: 2026-01-07 Ultima actualizacion: 2026-01-07 Version: 0.1.0

---

INFORMACION GENERAL

Proyecto:
  nombre: "template-saas"
  descripcion: "Template base para desarrollo de plataformas SaaS multi-tenant"
  tipo: "standalone"
  estado: "fase-0-preparacion"

Equipo:
  tech_lead: "Orquestador"
  repository: "workspace-v1/projects/template-saas"

Stack:
  database: "PostgreSQL 16+"
  backend: "Express.js + TypeScript"
  frontend: "React 18 + Vite"
  otros:
    - "Stripe (pagos)"
    - "Zustand (state)"
    - "Tailwind CSS 4"

---

VARIABLES DEL PROYECTO (ALIAS RESUELTOS)

Database

DB_NAME: "template_saas_platform"
DB_DDL_PATH: "apps/database/ddl"
DB_SCRIPTS_PATH: "apps/database/scripts"
DB_SEEDS_PATH: "apps/database/seeds"
RECREATE_CMD: "drop-and-recreate-database.sh"

SCHEMAS:
  - name: "auth"
    descripcion: "Autenticacion y sesiones"
  - name: "tenants"
    descripcion: "Multi-tenancy y organizaciones"
  - name: "users"
    descripcion: "Usuarios y perfiles"
  - name: "rbac"
    descripcion: "Roles y permisos"
  - name: "billing"
    descripcion: "Suscripciones y pagos"
  - name: "plans"
    descripcion: "Planes y limites"
  - name: "notifications"
    descripcion: "Notificaciones"
  - name: "feature_flags"
    descripcion: "Feature toggles"
  - name: "audit"
    descripcion: "Auditoria y logs"

Backend

BACKEND_ROOT: "apps/backend"
BACKEND_SRC: "apps/backend/src"
BACKEND_TESTS: "apps/backend/tests"
BACKEND_PORT: "3100"

MODULES:
  - name: "auth"
    descripcion: "Autenticacion JWT, OAuth, MFA"
  - name: "tenants"
    descripcion: "Gestion de organizaciones"
  - name: "users"
    descripcion: "Usuarios con RBAC"
  - name: "billing"
    descripcion: "Suscripciones Stripe"
  - name: "plans"
    descripcion: "Planes y limites"
  - name: "onboarding"
    descripcion: "Flujo de registro"
  - name: "notifications"
    descripcion: "Email, push, in-app"
  - name: "feature-flags"
    descripcion: "Toggles por plan/tenant"
  - name: "audit"
    descripcion: "Auditoria de acciones"
  - name: "ai-integration"
    descripcion: "Wrapper multi-proveedor LLM"

Frontend

FRONTEND_ROOT: "apps/frontend"
FRONTEND_SRC: "apps/frontend/src"
FRONTEND_PORT: "5173"
API_BASE_URL: "http://localhost:3100/api"

PORTALS:
  - name: "user"
    descripcion: "Portal usuario final"
    ruta: "/"
  - name: "admin"
    descripcion: "Portal admin de tenant"
    ruta: "/admin"
  - name: "superadmin"
    descripcion: "Portal superadmin"
    ruta: "/superadmin"

---

ALIAS RESUELTOS PARA ESTE PROYECTO

# Codigo
@DDL:           "apps/database/ddl/schemas/"
@DDL_ROOT:      "apps/database/ddl/"
@SEEDS:         "apps/database/seeds/"
@SEEDS_DEV:     "apps/database/seeds/dev/"
@SEEDS_PROD:    "apps/database/seeds/prod/"
@DB_SCRIPTS:    "apps/database/scripts/"

@BACKEND:       "apps/backend/src/modules/"
@BACKEND_ROOT:  "apps/backend/"
@BACKEND_SHARED: "apps/backend/src/shared/"

@FRONTEND:      "apps/frontend/src/portals/"
@FRONTEND_ROOT: "apps/frontend/"
@FRONTEND_SHARED: "apps/frontend/src/shared/"

# Orchestration
@ORCH:          "orchestration/"
@INVENTORY:     "orchestration/inventarios/MASTER_INVENTORY.yml"
@INV_DB:        "orchestration/inventarios/DATABASE_INVENTORY.yml"
@INV_BE:        "orchestration/inventarios/BACKEND_INVENTORY.yml"
@INV_FE:        "orchestration/inventarios/FRONTEND_INVENTORY.yml"
@TRAZA_DB:      "orchestration/trazas/TRAZA-TAREAS-DATABASE.md"
@TRAZA_BE:      "orchestration/trazas/TRAZA-TAREAS-BACKEND.md"
@TRAZA_FE:      "orchestration/trazas/TRAZA-TAREAS-FRONTEND.md"

# Documentacion
@DOCS:          "docs/"
@GUIAS:         "docs/95-guias-desarrollo/"
@ADR:           "docs/architecture/adr/"

---

COMANDOS FRECUENTES

# Database
recrear_db: "cd apps/database/scripts && ./drop-and-recreate-database.sh"
crear_db: "cd apps/database/scripts && ./create-database.sh"
psql_connect: "psql -d template_saas_platform"

# Backend
build_be: "cd apps/backend && npm run build"
lint_be: "cd apps/backend && npm run lint"
test_be: "cd apps/backend && npm run test"
start_be: "cd apps/backend && npm run start:dev"

# Frontend
build_fe: "cd apps/frontend && npm run build"
lint_fe: "cd apps/frontend && npm run lint"
start_fe: "cd apps/frontend && npm run dev"

---

ESTRUCTURA DEL PROYECTO

template-saas/
├── apps/
│   ├── database/
│   │   ├── ddl/
│   │   │   └── schemas/{schema}/
│   │   ├── seeds/
│   │   │   ├── dev/
│   │   │   └── prod/
│   │   └── scripts/
│   │
│   ├── backend/
│   │   ├── src/
│   │   │   ├── shared/
│   │   │   └── modules/
│   │   │       └── {modulo}/
│   │   ├── tests/
│   │   └── package.json
│   │
│   └── frontend/
│       ├── src/
│       │   ├── portals/
│       │   │   ├── user/
│       │   │   ├── admin/
│       │   │   └── superadmin/
│       │   ├── shared/
│       │   └── stores/
│       └── package.json
│
├── docs/
│   ├── 00-vision-general/
│   ├── 01-modulos/SAAS-NNN-*/
│   ├── 02-integraciones/INT-NNN-*/
│   └── architecture/adr/
│
├── orchestration/
│   ├── 00-guidelines/
│   │   └── CONTEXTO-PROYECTO.md    <- ESTE ARCHIVO
│   ├── inventarios/
│   ├── trazas/
│   └── PROXIMA-ACCION.md
│
└── README.md

---

REFERENCIAS A CORE/ORCHESTRATION

SIMCO:
  indice: "../../orchestration/directivas/simco/_INDEX.md"
  principios: "../../orchestration/directivas/principios/"
  aliases_globales: "../../orchestration/referencias/ALIASES.yml"
  perfiles: "../../orchestration/agents/perfiles/"

CATALOGO:
  indice: "../../shared/catalog/CATALOG-INDEX.yml"
  reutilizar: "../../orchestration/directivas/simco/SIMCO-REUTILIZAR.md"
  funcionalidades:
    - auth: "../../shared/catalog/auth/"
    - session: "../../shared/catalog/session-management/"
    - rate-limiting: "../../shared/catalog/rate-limiting/"
    - notifications: "../../shared/catalog/notifications/"
    - multi-tenancy: "../../shared/catalog/multi-tenancy/"
    - feature-flags: "../../shared/catalog/feature-flags/"
    - websocket: "../../shared/catalog/websocket/"
    - payments: "../../shared/catalog/payments/"
    - template-saas: "../../shared/catalog/template-saas/"

---

FUNCIONALIDADES DEL CATALOGO USADAS

funcionalidades_del_catalogo:
  - nombre: "auth"
    version: "1.0.0"
    adaptaciones: "Base JWT + OAuth + MFA"
    fecha_implementacion: "pendiente"
  - nombre: "multi-tenancy"
    version: "1.0.0"
    adaptaciones: "RLS por tenant_id"
    fecha_implementacion: "pendiente"
  - nombre: "payments"
    version: "1.0.0"
    adaptaciones: "Stripe Billing completo"
    fecha_implementacion: "pendiente"
  - nombre: "notifications"
    version: "1.0.0"
    adaptaciones: "Email + Push + In-app"
    fecha_implementacion: "pendiente"

---

NOTAS ESPECIFICAS DEL PROYECTO

Multi-Tenancy Strategy

• Cada tabla tiene columna tenant_id UUID NOT NULL
• RLS policies activas en todas las tablas
• Tenant ID en JWT claims
• Tenant context via middleware

Billing Model

• Planes: Free, Basic, Pro, Enterprise
• Ciclos: Monthly / Yearly
• Trial: 14 dias por defecto
• Metered billing opcional

Portal Architecture

• User Portal: React SPA, rutas protegidas por rol
• Admin Portal: Subruta /admin, TenantGuard
• Superadmin: Subruta /superadmin, SuperadminGuard

AI Integration

• Wrapper agnóstico para LLMs
• Soporte: Claude (Anthropic), GPT-4 (OpenAI), Gemini (Google)
• Token counting y cost tracking
• Rate limiting por tenant

---

Creado: 2026-01-07 Autor: Orquestador Basado en: TEMPLATE-CONTEXTO-PROYECTO.md v1.1.0