docs: fix remaining warnings in SaaS design spec (round 2)

- Fix metadata.json shown as unencrypted in tree (now .enc)
- Fix admin bypass order in checkPlanLimits (moved before status check)
- Add PM2 cross-worker cache invalidation via process messaging
- Fix fiel_credentials "no changes" contradiction with per-component IV
- Backup all tenant DBs regardless of active status

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/superpowers/specs/2026-03-15-saas-transformation-design.md

@@ -0,0 +1,797 @@
+# Horux360 SaaS Transformation — Design Spec
+
+**Date:** 2026-03-15
+**Status:** Approved
+**Author:** Carlos Horux + Claude
+
+## Overview
+
+Transform Horux360 from an internal multi-tenant accounting tool into a production-ready SaaS platform. Client registration remains manual (sales-led). Each client gets a fully isolated PostgreSQL database. Payments via MercadoPago. Transactional emails via Gmail SMTP (@horuxfin.com). Production deployment on existing server (192.168.10.212).
+
+**Target scale:** 10-50 clients within 6 months.
+
+**Starting from scratch:** No data migration. Existing schemas/data will be archived. Fresh setup.
+
+---
+
+## Section 1: Database-Per-Tenant Architecture
+
+### Rationale
+
+Clients sign NDAs requiring complete data isolation. Schema-per-tenant (current approach) shares a single database. Database-per-tenant provides:
+- Independent backup/restore per client
+- No risk of cross-tenant data leakage
+- Each DB can be moved to a different server if needed
+
+### Structure
+
+```
+PostgreSQL Server (max_connections: 300)
+├── horux360                  ← Central DB (Prisma-managed)
+├── horux_cas2408138w2        ← Client DB (raw SQL)
+├── horux_roem691011ez4       ← Client DB
+└── ...
+```
+
+### Central DB (`horux360`) — Prisma-managed tables
+
+Existing tables (modified):
+- `tenants` — add `database_name` column, remove `schema_name`
+- `users` — no changes
+- `refresh_tokens` — flush all existing tokens at migration cutover (invalidate all sessions)
+- `fiel_credentials` — no changes
+
+New tables:
+- `subscriptions` — MercadoPago subscription tracking
+- `payments` — payment history
+
+### Prisma schema migration
+
+The Prisma schema (`apps/api/prisma/schema.prisma`) must be updated:
+- Replace `schema_name String @unique @map("schema_name")` with `database_name String @unique @map("database_name")` on the `Tenant` model
+- Add `Subscription` and `Payment` models
+- Run `prisma migrate dev` to generate and apply migration
+- Update `Tenant` type in `packages/shared/src/types/tenant.ts`: replace `schemaName` with `databaseName`
+
+### JWT payload migration
+
+The current JWT payload embeds `schemaName`. This must change:
+- Update `JWTPayload` in `packages/shared/src/types/auth.ts`: replace `schemaName` with `databaseName`
+- Update token generation in `auth.service.ts`: read `tenant.databaseName` instead of `tenant.schemaName`
+- Update `refreshTokens` function to embed `databaseName`
+- At migration cutover: flush `refresh_tokens` table to invalidate all existing sessions (forces re-login)
+
+### Client DB naming
+
+Formula: `horux_<rfc_normalized>`
+```
+RFC "CAS2408138W2" → horux_cas2408138w2
+RFC "TPR840604D98" → horux_tpr840604d98
+```
+
+### Client DB tables (created via raw SQL)
+
+Each client database contains these tables (no schema prefix, direct `public` schema):
+
+- `cfdis` — with indexes: fecha_emision DESC, tipo, rfc_emisor, rfc_receptor, pg_trgm on nombre_emisor/nombre_receptor, uuid_fiscal unique
+- `iva_mensual`
+- `isr_mensual`
+- `alertas`
+- `calendario_fiscal`
+
+### TenantConnectionManager
+
+```typescript
+class TenantConnectionManager {
+  private pools: Map<string, { pool: pg.Pool; lastAccess: Date }>;
+  private cleanupInterval: NodeJS.Timer;
+
+  // Get or create a pool for a tenant
+  getPool(tenantId: string, databaseName: string): pg.Pool;
+
+  // Create a new tenant database with all tables and indexes
+  provisionDatabase(rfc: string): Promise<string>;
+
+  // Drop a tenant database (soft-delete: rename to horux_deleted_<rfc>_<timestamp>)
+  deprovisionDatabase(databaseName: string): Promise<void>;
+
+  // Cleanup idle pools (called every 60s, removes pools idle > 5min)
+  private cleanupIdlePools(): void;
+}
+```
+
+Pool configuration per tenant:
+- `max`: 3 connections (with 2 PM2 cluster instances, this means 6 connections/tenant max; at 50 tenants = 300, matching `max_connections`)
+- `idleTimeoutMillis`: 300000 (5 min)
+- `connectionTimeoutMillis`: 10000 (10 sec)
+
+**Note on PM2 cluster mode:** Each PM2 worker is a separate Node.js process with its own `TenantConnectionManager` instance. With `instances: 2` and `max: 3` per pool, worst case is 50 tenants × 3 connections × 2 workers = 300 connections, which matches `max_connections = 300`. If scaling beyond 50 tenants, either increase `max_connections` or reduce pool `max` to 2.
+
+### Tenant middleware change
+
+Current: Sets `search_path` on a shared connection.
+New: Returns a dedicated pool connected to the tenant's own database.
+
+```typescript
+// Before
+req.tenantSchema = schema;
+await pool.query(`SET search_path TO "${schema}", public`);
+
+// After
+req.tenantPool = tenantConnectionManager.getPool(tenant.id, tenant.databaseName);
+```
+
+All tenant service functions change from using a shared pool with schema prefix to using `req.tenantPool` with direct table names.
+
+### Admin impersonation (X-View-Tenant)
+
+The current `X-View-Tenant` header support for admin "view-as" functionality is preserved. The new middleware resolves the `databaseName` for the viewed tenant:
+
+```typescript
+// If admin is viewing another tenant
+if (req.headers['x-view-tenant'] && req.user.role === 'admin') {
+  const viewedTenant = await getTenantByRfc(req.headers['x-view-tenant']);
+  req.tenantPool = tenantConnectionManager.getPool(viewedTenant.id, viewedTenant.databaseName);
+} else {
+  req.tenantPool = tenantConnectionManager.getPool(tenant.id, tenant.databaseName);
+}
+```
+
+### Provisioning flow (new client)
+
+1. Admin creates tenant via UI → POST `/api/tenants/`
+2. Insert record in `horux360.tenants` with `database_name`
+3. Execute `CREATE DATABASE horux_<rfc>`
+4. Connect to new DB, create all tables + indexes
+5. Create admin user in `horux360.users` linked to tenant
+6. Send welcome email with temporary credentials
+7. Generate MercadoPago subscription link
+
+**Rollback on partial failure:** If any step 3-7 fails:
+- Drop the created database if it exists (`DROP DATABASE IF EXISTS horux_<rfc>`)
+- Delete the `tenants` row
+- Delete the `users` row if created
+- Return error to admin with the specific step that failed
+- The entire provisioning is wrapped in a try/catch with explicit cleanup
+
+### PostgreSQL tuning
+
+```
+max_connections = 300
+shared_buffers = 4GB
+work_mem = 16MB
+effective_cache_size = 16GB
+maintenance_work_mem = 512MB
+```
+
+### Server disk
+
+Expand from 29 GB to 100 GB to accommodate:
+- 25-50 client databases (~2-3 GB total)
+- Daily backups with 7-day retention (~15 GB)
+- FIEL encrypted files (<100 MB)
+- Logs, builds, OS (~10 GB)
+
+---
+
+## Section 2: SAT Credential Storage (FIEL)
+
+### Dual storage strategy
+
+When a client uploads their FIEL (.cer + .key + password):
+
+**A. Filesystem (for manual linking):**
+```
+/var/horux/fiel/
+├── CAS2408138W2/
+│   ├── certificate.cer.enc     ← AES-256-GCM encrypted
+│   ├── private_key.key.enc     ← AES-256-GCM encrypted
+│   └── metadata.json.enc       ← serial, validity dates, upload date (also encrypted)
+└── ROEM691011EZ4/
+    ├── certificate.cer.enc
+    ├── private_key.key.enc
+    └── metadata.json.enc
+```
+
+**B. Central DB (`fiel_credentials` table):**
+- Existing structure: `cer_data`, `key_data`, `key_password_encrypted`, `encryption_iv`, `encryption_tag`
+- **Schema change required:** Add per-component IV/tag columns (`cer_iv`, `cer_tag`, `key_iv`, `key_tag`, `password_iv`, `password_tag`) to support independent encryption per component. Alternatively, use a single JSON column for all encryption metadata. The existing `encryption_iv` and `encryption_tag` columns can be dropped after migration.
+
+### Encryption
+
+- Algorithm: AES-256-GCM
+- Key: `FIEL_ENCRYPTION_KEY` environment variable (separate from other secrets)
+- **Code change required:** `sat-crypto.service.ts` currently derives the key from `JWT_SECRET` via `createHash('sha256').update(env.JWT_SECRET).digest()`. This must be changed to read `FIEL_ENCRYPTION_KEY` from the env schema. The `env.ts` Zod schema must be updated to declare `FIEL_ENCRYPTION_KEY` as required.
+- Each component (certificate, private key, password) is encrypted separately with its own IV and auth tag. The `fiel_credentials` table stores separate `encryption_iv` and `encryption_tag` per row. The filesystem also stores each file independently encrypted.
+- **Code change required:** The current `sat-crypto.service.ts` shares a single IV/tag across all three components. Refactor to encrypt each component independently with its own IV/tag. Store per-component IV/tags in the DB (add columns: `cer_iv`, `cer_tag`, `key_iv`, `key_tag`, `password_iv`, `password_tag` — or use a JSON column).
+- Password is encrypted, never stored in plaintext
+
+### Manual decryption CLI
+
+```bash
+node scripts/decrypt-fiel.js --rfc CAS2408138W2
+```
+
+- Decrypts files to `/tmp/horux-fiel-<rfc>/`
+- Files auto-delete after 30 minutes (via setTimeout or tmpwatch)
+- Requires SSH access to server
+
+### Security
+
+- `/var/horux/fiel/` permissions: `700` (root only)
+- Encrypted files are useless without `FIEL_ENCRYPTION_KEY`
+- `metadata.json` is also encrypted (contains serial number + RFC which could be used to query SAT's certificate validation service, violating NDA confidentiality requirements)
+
+### Upload flow
+
+1. Client navigates to `/configuracion/sat`
+2. Uploads `.cer` + `.key` files + enters password
+3. API validates the certificate (checks it's a valid FIEL, not expired)
+4. Encrypts and stores in both filesystem and database
+5. Sends notification email to admin team: "Cliente X subió su FIEL"
+
+---
+
+## Section 3: Payment System (MercadoPago)
+
+### Integration approach
+
+Using MercadoPago's **Preapproval (Subscription)** API for recurring payments.
+
+### New tables in central DB
+
+```sql
+CREATE TABLE subscriptions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id UUID NOT NULL REFERENCES tenants(id),
+    plan VARCHAR(20) NOT NULL,
+    mp_preapproval_id VARCHAR(100),
+    status VARCHAR(20) NOT NULL DEFAULT 'pending',
+    -- status: pending | authorized | paused | cancelled
+    amount DECIMAL(10,2) NOT NULL,
+    frequency VARCHAR(10) NOT NULL DEFAULT 'monthly',
+    -- frequency: monthly | yearly
+    current_period_start TIMESTAMP,
+    current_period_end TIMESTAMP,
+    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_subscriptions_tenant_id ON subscriptions(tenant_id);
+CREATE INDEX idx_subscriptions_status ON subscriptions(status);
+
+CREATE TABLE payments (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id UUID NOT NULL REFERENCES tenants(id),
+    subscription_id UUID REFERENCES subscriptions(id),
+    mp_payment_id VARCHAR(100),
+    amount DECIMAL(10,2) NOT NULL,
+    status VARCHAR(20) NOT NULL DEFAULT 'pending',
+    -- status: approved | pending | rejected | refunded
+    payment_method VARCHAR(50),
+    paid_at TIMESTAMP,
+    created_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_payments_tenant_id ON payments(tenant_id);
+CREATE INDEX idx_payments_subscription_id ON payments(subscription_id);
+```
+
+### Plans and pricing
+
+Defined in `packages/shared/src/constants/plans.ts` (update existing):
+
+| Plan | Monthly price (MXN) | CFDIs | Users | Features |
+|------|---------------------|-------|-------|----------|
+| starter | Configurable | 100 | 1 | dashboard, cfdi_basic, iva_isr |
+| business | Configurable | 500 | 3 | + reportes, alertas, calendario |
+| professional | Configurable | 2,000 | 10 | + xml_sat, conciliacion, forecasting |
+| enterprise | Configurable | Unlimited | Unlimited | + api, multi_empresa |
+
+Prices are configured from admin panel, not hardcoded.
+
+### Subscription flow
+
+1. Admin creates tenant and assigns plan
+2. Admin clicks "Generate payment link" → API creates MercadoPago Preapproval
+3. Link is sent to client via email
+4. Client pays → MercadoPago sends webhook
+5. System activates subscription, records payment
+
+### Webhook endpoint
+
+`POST /api/webhooks/mercadopago` (public, no auth)
+
+Validates webhook signature using `x-signature` header and `x-request-id`.
+
+Events handled:
+- `payment` → query MercadoPago API for payment details → insert into `payments`, update subscription period
+- `subscription_preapproval` → update subscription status (authorized, paused, cancelled)
+
+On payment failure or subscription cancellation:
+- Mark tenant `active = false`
+- Client gets read-only access (can view data but not upload CFDIs, generate reports, etc.)
+
+### Admin panel additions
+
+- View subscription status per client (active, amount, next billing date)
+- Generate payment link button
+- "Mark as paid manually" button (for bank transfer payments)
+- Payment history per client
+
+### Client panel additions
+
+- New section in `/configuracion`: "Mi suscripción"
+- Shows: current plan, next billing date, payment history
+- Client cannot change plan themselves (admin does it)
+
+### Environment variables
+
+```
+MP_ACCESS_TOKEN=<mercadopago_access_token>
+MP_WEBHOOK_SECRET=<webhook_signature_secret>
+MP_NOTIFICATION_URL=https://horux360.consultoria-as.com/api/webhooks/mercadopago
+```
+
+---
+
+## Section 4: Transactional Emails
+
+### Transport
+
+Nodemailer with Gmail SMTP (Google Workspace).
+
+```
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=<user>@horuxfin.com
+SMTP_PASS=<google_app_password>
+SMTP_FROM=Horux360 <noreply@horuxfin.com>
+```
+
+Requires generating an App Password in Google Workspace admin.
+
+### Email types
+
+| Event | Recipient | Subject |
+|-------|-----------|---------|
+| Client registered | Client | Bienvenido a Horux360 |
+| FIEL uploaded | Admin team | [Cliente] subió su FIEL |
+| Payment received | Client | Confirmación de pago - Horux360 |
+| Payment failed | Client + Admin | Problema con tu pago - Horux360 |
+| Subscription expiring | Client | Tu suscripción vence en 5 días |
+| Subscription cancelled | Client + Admin | Suscripción cancelada - Horux360 |
+
+### Template approach
+
+HTML templates as TypeScript template literal functions. No external template engine.
+
+```typescript
+// services/email/templates/welcome.ts
+export function welcomeEmail(data: { nombre: string; email: string; tempPassword: string; loginUrl: string }): string {
+  return `<!DOCTYPE html>...`;
+}
+```
+
+Each template:
+- Responsive HTML email (inline CSS)
+- Horux360 branding (logo, colors)
+- Plain text fallback
+
+### Email service
+
+```typescript
+class EmailService {
+  sendWelcome(to: string, data: WelcomeData): Promise<void>;
+  sendFielNotification(data: FielNotificationData): Promise<void>;
+  sendPaymentConfirmation(to: string, data: PaymentData): Promise<void>;
+  sendPaymentFailed(to: string, data: PaymentData): Promise<void>;
+  sendSubscriptionExpiring(to: string, data: SubscriptionData): Promise<void>;
+  sendSubscriptionCancelled(to: string, data: SubscriptionData): Promise<void>;
+}
+```
+
+### Limits
+
+Gmail Workspace: 500 emails/day. Expected volume for 25 clients: ~50-100 emails/month. Well within limits.
+
+---
+
+## Section 5: Production Deployment
+
+### Build pipeline
+
+**API:**
+```bash
+cd apps/api && pnpm build    # tsc → dist/
+pnpm start                    # node dist/index.js
+```
+
+**Web:**
+```bash
+cd apps/web && pnpm build    # next build → .next/
+pnpm start                    # next start (optimized server)
+```
+
+### PM2 configuration
+
+```javascript
+// ecosystem.config.js
+module.exports = {
+  apps: [
+    {
+      name: 'horux-api',
+      script: 'dist/index.js',
+      cwd: '/root/Horux/apps/api',
+      instances: 2,
+      exec_mode: 'cluster',
+      env: { NODE_ENV: 'production' }
+    },
+    {
+      name: 'horux-web',
+      script: 'node_modules/.bin/next',
+      args: 'start',
+      cwd: '/root/Horux/apps/web',
+      instances: 1,
+      exec_mode: 'fork',
+      env: { NODE_ENV: 'production' }
+    }
+  ]
+};
+```
+
+Auto-restart on crash. Log rotation via `pm2-logrotate`.
+
+### Nginx reverse proxy
+
+```nginx
+# Rate limiting zone definitions (in http block of nginx.conf)
+limit_req_zone $binary_remote_addr zone=auth:10m rate=5r/m;
+limit_req_zone $binary_remote_addr zone=webhooks:10m rate=30r/m;
+
+server {
+    listen 80;
+    server_name horux360.consultoria-as.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name horux360.consultoria-as.com;
+
+    ssl_certificate /etc/letsencrypt/live/horux360.consultoria-as.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/horux360.consultoria-as.com/privkey.pem;
+
+    # Security headers
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header X-Frame-Options DENY;
+    add_header X-Content-Type-Options nosniff;
+
+    # Gzip
+    gzip on;
+    gzip_types text/plain application/json application/javascript text/css;
+
+    # Health check (for monitoring)
+    location /api/health {
+        proxy_pass http://127.0.0.1:4000;
+    }
+
+    # Rate limiting for public endpoints
+    location /api/auth/ {
+        limit_req zone=auth burst=5 nodelay;
+        proxy_pass http://127.0.0.1:4000;
+    }
+
+    location /api/webhooks/ {
+        limit_req zone=webhooks burst=10 nodelay;
+        proxy_pass http://127.0.0.1:4000;
+    }
+
+    # API
+    location /api/ {
+        proxy_pass http://127.0.0.1:4000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        client_max_body_size 200M;  # Bulk XML uploads (200MB is enough for ~50k XML files)
+    }
+
+    # Next.js
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+### Health check endpoint
+
+The existing `GET /health` endpoint returns `{ status: 'ok', timestamp }`. PM2 uses this for liveness checks. Nginx can optionally use it for upstream health monitoring.
+
+### SSL
+
+Let's Encrypt with certbot. Auto-renewal via cron.
+
+```bash
+certbot --nginx -d horux360.consultoria-as.com
+```
+
+### Firewall
+
+```bash
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP (redirect to HTTPS)
+ufw allow 443/tcp   # HTTPS
+ufw enable
+```
+
+PostgreSQL only on localhost (no external access).
+
+### Backups
+
+Cron job at **1:00 AM** daily (runs before SAT cron at 3:00 AM, with enough gap to complete):
+
+**Authentication:** Create a `.pgpass` file at `/root/.pgpass` with `localhost:5432:*:postgres:<password>` and `chmod 600`. This allows `pg_dump` to authenticate without inline passwords.
+
+```bash
+#!/bin/bash
+# /var/horux/scripts/backup.sh
+set -euo pipefail
+
+BACKUP_DIR=/var/horux/backups
+DATE=$(date +%Y-%m-%d)
+DOW=$(date +%u)  # Day of week: 1=Monday, 7=Sunday
+DAILY_DIR=$BACKUP_DIR/daily
+WEEKLY_DIR=$BACKUP_DIR/weekly
+
+mkdir -p $DAILY_DIR $WEEKLY_DIR
+
+# Backup central DB
+pg_dump -h localhost -U postgres horux360 | gzip > $DAILY_DIR/horux360_$DATE.sql.gz
+
+# Backup each tenant DB
+for db in $(psql -h localhost -U postgres -t -c "SELECT database_name FROM tenants WHERE database_name IS NOT NULL" horux360); do
+    db_trimmed=$(echo $db | xargs)  # trim whitespace
+    pg_dump -h localhost -U postgres "$db_trimmed" | gzip > $DAILY_DIR/${db_trimmed}_${DATE}.sql.gz
+done
+
+# On Sundays, copy to weekly directory
+if [ "$DOW" -eq 7 ]; then
+    cp $DAILY_DIR/*_${DATE}.sql.gz $WEEKLY_DIR/
+fi
+
+# Remove daily backups older than 7 days
+find $DAILY_DIR -name "*.sql.gz" -mtime +7 -delete
+
+# Remove weekly backups older than 28 days
+find $WEEKLY_DIR -name "*.sql.gz" -mtime +28 -delete
+
+# Verify backup files are not empty (catch silent pg_dump failures)
+for f in $DAILY_DIR/*_${DATE}.sql.gz; do
+    if [ ! -s "$f" ]; then
+        echo "WARNING: Empty backup file: $f" >&2
+    fi
+done
+```
+
+**Schedule separation:** Backups run at 1:00 AM, SAT cron runs at 3:00 AM. With 50 clients, backup should complete in ~15-30 minutes, leaving ample gap before SAT sync starts.
+
+### Environment variables (production)
+
+```
+NODE_ENV=production
+PORT=4000
+DATABASE_URL=postgresql://postgres:<strong_password>@localhost:5432/horux360?schema=public
+JWT_SECRET=<cryptographically_secure_random_64_chars>
+JWT_EXPIRES_IN=24h
+JWT_REFRESH_EXPIRES_IN=30d
+CORS_ORIGIN=https://horux360.consultoria-as.com
+FIEL_ENCRYPTION_KEY=<separate_32_byte_hex_key>
+MP_ACCESS_TOKEN=<mercadopago_production_token>
+MP_WEBHOOK_SECRET=<webhook_secret>
+MP_NOTIFICATION_URL=https://horux360.consultoria-as.com/api/webhooks/mercadopago
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=<user>@horuxfin.com
+SMTP_PASS=<google_app_password>
+SMTP_FROM=Horux360 <noreply@horuxfin.com>
+ADMIN_EMAIL=admin@horuxfin.com
+```
+
+### SAT cron
+
+Already implemented. Runs at 3:00 AM when `NODE_ENV=production`. Will activate automatically with the environment change.
+
+---
+
+## Section 6: Plan Enforcement & Feature Gating
+
+### Enforcement middleware
+
+```typescript
+// middleware: checkPlanLimits
+async function checkPlanLimits(req, res, next) {
+  const tenant = await getTenantWithCache(req.user.tenantId); // cached 5 min
+  const subscription = await getActiveSubscription(tenant.id);
+
+  // Admin-impersonated requests bypass subscription check
+  // (admin needs to complete client setup regardless of payment status)
+  if (req.headers['x-view-tenant'] && req.user.role === 'admin') {
+    return next();
+  }
+
+  // Allowed statuses: 'authorized' (paid) or 'pending' (grace period for new clients)
+  const allowedStatuses = ['authorized', 'pending'];
+
+  // Check subscription status
+  if (!subscription || !allowedStatuses.includes(subscription.status)) {
+    // Allow read-only access for cancelled/paused subscriptions
+    if (req.method !== 'GET') {
+      return res.status(403).json({
+        message: 'Suscripción inactiva. Contacta soporte para reactivar.'
+      });
+    }
+  }
+
+  next();
+}
+```
+
+**Grace period:** New clients start with `status: 'pending'` and have full write access (can upload FIEL, upload CFDIs, etc.). Once the subscription moves to `'cancelled'` or `'paused'` (e.g., failed payment), write access is revoked. Admin can also manually set status to `'authorized'` for clients who pay by bank transfer.
+
+### CFDI limit check
+
+Applied on `POST /api/cfdi/` and `POST /api/cfdi/bulk`:
+
+```typescript
+async function checkCfdiLimit(req, res, next) {
+  const tenant = await getTenantWithCache(req.user.tenantId);
+  if (tenant.cfdiLimit === -1) return next(); // unlimited
+
+  const currentCount = await getCfdiCountWithCache(req.tenantPool); // cached 5 min
+  const newCount = Array.isArray(req.body) ? req.body.length : 1;
+
+  if (currentCount + newCount > tenant.cfdiLimit) {
+    return res.status(403).json({
+      message: `Límite de CFDIs alcanzado (${currentCount}/${tenant.cfdiLimit}). Contacta soporte para upgrade.`
+    });
+  }
+
+  next();
+}
+```
+
+### User limit check
+
+Applied on `POST /api/usuarios/invite` (already partially exists):
+
+```typescript
+const userCount = await getUserCountForTenant(tenantId);
+if (userCount >= tenant.usersLimit && tenant.usersLimit !== -1) {
+  return res.status(403).json({
+    message: `Límite de usuarios alcanzado (${userCount}/${tenant.usersLimit}).`
+  });
+}
+```
+
+### Feature gating
+
+Applied per route using the existing `hasFeature()` function from shared:
+
+```typescript
+function requireFeature(feature: string) {
+  return async (req, res, next) => {
+    const tenant = await getTenantWithCache(req.user.tenantId);
+    if (!hasFeature(tenant.plan, feature)) {
+      return res.status(403).json({
+        message: 'Tu plan no incluye esta función. Contacta soporte para upgrade.'
+      });
+    }
+    next();
+  };
+}
+
+// Usage in routes:
+router.get('/reportes', authenticate, requireFeature('reportes'), reportesController);
+router.get('/alertas', authenticate, requireFeature('alertas'), alertasController);
+```
+
+### Feature matrix
+
+| Feature key | Starter | Business | Professional | Enterprise |
+|-------------|---------|----------|-------------|------------|
+| dashboard | Yes | Yes | Yes | Yes |
+| cfdi_basic | Yes | Yes | Yes | Yes |
+| iva_isr | Yes | Yes | Yes | Yes |
+| reportes | No | Yes | Yes | Yes |
+| alertas | No | Yes | Yes | Yes |
+| calendario | No | Yes | Yes | Yes |
+| xml_sat | No | No | Yes | Yes |
+| conciliacion | No | No | Yes | Yes |
+| forecasting | No | No | Yes | Yes |
+| multi_empresa | No | No | No | Yes |
+| api_externa | No | No | No | Yes |
+
+### Frontend feature gating
+
+The sidebar/navigation hides menu items based on plan:
+
+```typescript
+const tenant = useTenantInfo(); // new hook
+const menuItems = allMenuItems.filter(item =>
+  !item.requiredFeature || hasFeature(tenant.plan, item.requiredFeature)
+);
+```
+
+Pages also show an "upgrade" message if accessed directly via URL without the required plan.
+
+### Caching
+
+Plan checks and CFDI counts are cached in-memory with 5-minute TTL to avoid database queries on every request.
+
+**Cache invalidation across PM2 workers:** Since each PM2 cluster worker has its own in-memory cache, subscription status changes (via webhook) must invalidate the cache in all workers. The webhook handler writes the status to the DB, then sends a `process.send()` message to the PM2 master which broadcasts to all workers to invalidate the specific tenant's cache entry. This ensures all workers reflect subscription changes within seconds, not minutes.
+
+---
+
+## Architecture Diagram
+
+```
+                    ┌─────────────────────┐
+                    │   Nginx (443/80)    │
+                    │  SSL + Rate Limit   │
+                    └──────────┬──────────┘
+                               │
+                ┌──────────────┼──────────────┐
+                │              │              │
+          ┌─────▼─────┐  ┌────▼────┐  ┌──────▼──────┐
+          │ Next.js   │  │ Express │  │  Webhook    │
+          │ :3000     │  │ API x2  │  │  Handler    │
+          │ (fork)    │  │ :4000   │  │  (no auth)  │
+          └───────────┘  │ (cluster)│  └──────┬──────┘
+                         └────┬────┘         │
+                              │              │
+                    ┌─────────▼──────────┐   │
+                    │ TenantConnection   │   │
+                    │ Manager            │   │
+                    │ (pool per tenant)  │   │
+                    └─────────┬──────────┘   │
+                              │              │
+           ┌──────────────────┼──────┐       │
+           │                  │      │       │
+     ┌─────▼─────┐  ┌───────▼┐  ┌──▼──┐    │
+     │ horux360  │  │horux_  │  │horux│    │
+     │ (central) │  │client1 │  │_... │    │
+     │           │  └────────┘  └─────┘    │
+     │ tenants   │                         │
+     │ users     │◄────────────────────────┘
+     │ subs      │    (webhook updates)
+     │ payments  │
+     └───────────┘
+
+     ┌───────────────┐    ┌─────────────┐
+     │ /var/horux/   │    │ Gmail SMTP  │
+     │ fiel/<rfc>/   │    │ @horuxfin   │
+     │ backups/      │    └─────────────┘
+     └───────────────┘
+
+     ┌───────────────┐
+     │ MercadoPago   │
+     │ Preapproval   │
+     │ API           │
+     └───────────────┘
+```
+
+---
+
+## Out of Scope
+
+- Landing page (already exists separately)
+- Self-service registration (clients are registered manually by admin)
+- Automatic SAT connector (manual FIEL linking for now)
+- Plan change by client (admin handles upgrades/downgrades)
+- Mobile app
+- Multi-region deployment