Folios PRODUCT PRINCIPLES · v1
Folios · Product Principles

Complex underneath.
Clear everywhere else.

Simple on the surface. Rigorous underneath. No vendemos que el compliance sea fácil — vendemos que Folios sabe manejar la complejidad para que no vivas dentro de ella.
Las tres capas

No simplificamos el compliance. Encapsulamos su complejidad.

┌──────────────────────────────────────────────┐
│              FOLIOS EXPERIENCE                │  ← absurdamente simple
│     "¿Qué quieres hacer?"  ·  Facturar $18,420 │
├──────────────────────────────────────────────┤
│              FOLIOS ENGINE                   │  ← puede ser sofisticadísimo
│  Identity · Rules · Documents · Validation     │
│  Ledger · Reconciliation · Evidence · Events   │
├──────────────────────────────────────────────┤
│            JURISDICTION LAYERS               │  ← puede ser horrible
│      MX  CFDI/SAT/PAC        US  Invoice/Tax    │
└──────────────────────────────────────────────┘

El usuario experimenta los 5 cm superiores. Nosotros nos obsesionamos con los 5 km inferiores. El usuario nunca paga el costo cognitivo de la tercera capa.

Los 13 principios
01

No preguntes lo que Folios ya sabe

Regla casi constitucional. Si HostCasa ya sabe cliente, propiedad, monto, moneda, país, fecha, concepto y método de pago, Folios no lo vuelve a preguntar.

Nueva factura · Casa de Barra · Estancia 4 noches $18,420.00 MXN · Para: Juan García [ Emitir factura ] ← debajo, 30 validaciones
02

Compliance Engine, no compliance en la UI

Las reglas fiscales no viven en invoice-form.tsx. Viven en un pipeline. La experiencia evoluciona independiente de la regulación.

Operation → Context → Jurisdiction → Rules → Validation → Document → Provider → Evidence → Ledger
03

Canonical Financial Record

Un objeto universal — FolioRecord — y adapters por jurisdicción. El núcleo habla Folios; los adapters hablan SAT, PAC, estados de EE.UU.

FolioRecord → [MX adapter → CFDI/XML/UUID/PAC] → [US adapter → Invoice/Receipt/Tax]
04

Progressive disclosure

Mismo sistema, distinta profundidad. No hacemos la UI simple quitando capacidades — la hacemos simple mostrando capacidad cuando corresponde. Usuario / Contador / Developer / Compliance.

05

Folios habla humano; el sistema habla fiscal

«¿Para qué usará esta factura?» en vez de UsoCFDI. Nunca CFDI ERROR 301 — Folios traduce, con «Ver detalle técnico →» para quien lo necesite. Absorbe burocracia, devuelve claridad.

06

Estados, no errores

Casi nada debe sentirse como «el sistema explotó».

○ Draft ◌ Preparing ◌ Validating ● Issued ! Needs attention PAC lento → "Estamos terminando esta factura." (retry 2/5, idempotency_key…)
07

Needs attention

El usuario no administra compliance. Folios lo administra y ocasionalmente dice: «3 cosas necesitan tu atención». Folios encuentra las excepciones; el humano las resuelve.

08

Happy path corto; exception path excelente

95%: Operation → Folios → Done ●. La excepción no se esconde, se organiza: dice exactamente qué falta y qué ya tenemos.

09

Jamás fingir compliance

La línea roja. Nunca «Todo correcto ✓» cuando no sabemos. Tres estados distintos, nunca mezclados, con evidencia de cada paso:

VALIDATED BY FOLIOS → VALIDATED BY PROVIDER → ACCEPTED BY AUTHORITY
10

Compliance as code

Reglas versionadas, testeables, fechadas, explicables y auditables. Astelar documenta: qué cambió → por qué → qué afecta → qué tests lo prueban → desde cuándo.

rule_set: mx-cfdi-4 · version: 2026.08 · effective_from: 2026-08-01
11

El ledger es sagrado

Historial append-only de lo ocurrido. Si preguntan «¿por qué Folios emitió esto?», reconstruimos la respuesta. Ahí la simplicidad del frontend gana credibilidad institucional.

12

UX ≠ source of truth

Aunque el botón diga «Emitir», el backend revalida: identidad → permisos → jurisdicción → reglas → duplicados → importes → estado → idempotencia. La interfaz es una representación amable; el engine es la autoridad.

13

El efecto Fondeadora

La magia no es menos complejidad. Es que el usuario vive los 5 cm de arriba (Done ●) mientras nosotros nos obsesionamos con los 5 km de abajo: identity, jurisdiction, tax rules, validation, providers, retries, idempotency, reconciliation, evidence, audit trail, regulatory versioning.

Contabilidad & downstream

La segunda familia de adapters

Folios no reemplaza los libros — los alimenta con un asiento ya reconciliado, para que nadie recapture nada. Reconcilia primero (operación ↔ pago ↔ documento), sincroniza después.

              FOLIO RECORD (+ ledger)
                     │
   ┌─────────────────┼──────────────────┐
 JURISDICTION ADAPTERS        ACCOUNTING ADAPTERS
 MX CFDI/SAT/PAC              MX  CONTPAQi · Aspel · Alegra · Odoo
 US Invoice/Tax              US  QuickBooks · Xero · NetSuite · Sage

Folios es dueño del record de la operación; la contabilidad, de los libros. Reconciliar ese desmadre intermedio —entre operaciones (HostCasa, POS, bookings) y los libros— es el moat.

Guardrails
  • Encapsular la complejidad
  • Pre-llenar todo lo que ya sabemos
  • Traducir fiscal → humano
  • El ledger sagrado
  • Revalidar en el backend
  • Versionar reglas como código
  • Excepciones como "needs attention"
No
  • Dispersar reglas por la UI
  • Fingir un check verde
  • Universos de factura por país
  • Hacer navegar módulos de compliance
  • Que la UI sea la fuente de verdad
  • Prometer "compliance fácil"
Complex underneath.
Clear everywhere else.

Folios no quiere ser el software detrás de la factura. Quiere ser la marca al frente de la categoría — y esta arquitectura es lo que se lo permite sin convertirse en el ERP monstruoso que reemplaza.