Arquitectura de Referencia para AppFolio
Resumen
Arquitectura de producción para integraciones de gestión de propiedades con la API AppFolio Stack. Diseñada para carteras de múltiples propiedades que requieren seguimiento de vacantes en tiempo real, gestión del ciclo de vida de inquilinos, enrutamiento de órdenes de trabajo y conciliación contable. Factores clave de diseño: frescura de datos para decisiones de arrendamiento, sincronización idempotente para precisión financiera y capacidad de respuesta del portal del inquilino.
Prerrequisitos
- Un contrato verificado por el proveedor para endpoints, autenticación, eventos (si los hay), límites de tasa, residencia de datos y efectos contables/CRM permisibles posteriores.
- Entornos de staging y producción separados con secretos gestionados, fixtures sintéticos, colas duraderas/almacenes de idempotencia y propietarios de conciliación designados.
- Clasificación de datos que limite los modelos de dashboard y caché a los campos permitidos más pequeños; los datos de contacto, pago y saldo de inquilinos requieren almacenes cifrados separados y controles de acceso.
Instrucciones
- Construya primero la capa de cliente y servicio de solo lectura con límites de contrato, presupuestos de endpoint, entradas de caché minimizadas y observabilidad antes de agregar escritura o procesamiento de eventos.
- Habilite los eventos del proveedor solo después de que el contrato y los límites de cuerpo sin procesar duraderos, firma, persistencia y reproducción hayan sido probados; de lo contrario, use conciliación incremental acotada.
- Persista un registro de idempotencia/conciliación antes de cualquier mutación de orden de trabajo, contabilidad, inquilino o arrendamiento y requiera autorización explícita.
- Valide la arquitectura en staging con datos sintéticos, una falla forzada del proveedor, evento duplicado/reintento y ensayo de reversión antes de la promoción.
Diagrama de Arquitectura
Dashboard (React) ──→ Servicio de Propiedades ──→ Caché Redis ──→ API AppFolio Stack
↓ /properties
Cola (Bull) ──→ Trabajador de Sincronización /tenants
↓ /leases
Manejador de Eventos ←── Eventos del proveedor* /work-orders
↓ /bills
Sincronización Contable ──→ QuickBooks/Xero
* Use eventos del proveedor solo cuando el contrato activo confirme su entrega
y semántica de seguridad; de lo contrario, alimente la cola desde la conciliación acotada.
Capa de Servicio
class PropertyService {
constructor(private client: AppFolioClient, private cache: CacheLayer) {}
async getPortfolioSummary(propertyIds: string[]): Promise<PortfolioSummary> {
const properties = await Promise.all(
propertyIds.map(id => this.cache.getOrFetch(`prop:${id}`, () => this.client.get(`/properties/${id}`)))
);
return { totalUnits: properties.reduce((sum, p) => sum + p.units.length, 0),
vacancyRate: this.calcVacancy(properties), pendingWorkOrders: await this.getPendingOrders(propertyIds) };
}
async routeWorkOrder(order: WorkOrderRequest): Promise<string> {
const property = await this.client.get(`/properties/${order.propertyId}`);
const vendor = this.selectVendor(property.region, order.category);
return this.client.post('/work-orders', { ...order, assigned_vendor: vendor });
}
}
Estrategia de Caché
const CACHE_CONFIG = {
properties: { ttl: 300, prefix: 'prop' }, // 5 min — cambios poco frecuentes
tenants: { ttl: 120, prefix: 'tenant' }, // 2 min — rotación moderada
leases: { ttl: 60, prefix: 'lease' }, // 1 min — precisión financiera
workOrders: { ttl: 30, prefix: 'wo' }, // 30s — seguimiento en tiempo real
vacancies: { ttl: 15, prefix: 'vacancy' }, // 15s — la velocidad de arrendamiento importa
};
// Invalidación impulsada por webhooks: los eventos de AppFolio vacían las claves de caché coincidentes inmediatamente
Pipeline de Eventos
class PropertyEventPipeline {
private queue = new Bull('appfolio-events', { redis: process.env.REDIS_URL });
async onWebhook(event: AppFolioEvent): Promise<void> {
await this.queue.add(event.type, event, { attempts: 3, backoff: { type: 'exponential', delay: 2000 } });
}
async processLeaseEvent(event: LeaseEvent): Promise<void> {
if (event.type === 'lease.signed') await this.updateVacancy(event.propertyId);
if (event.type === 'lease.terminated') await this.triggerMoveOutWorkflow(event);
}
async processWorkOrderEvent(event: WorkOrderEvent): Promise<void> {
if (event.status === 'completed') await this.reconcileVendorInvoice(event);
}
}
Modelo de Datos
interface Property { id: string; name: string; address: Address; units: Unit[]; region: string; }
interface TenantRef { id: string; leaseId: string; contactCiphertextRef: string; }
interface Lease { id: string; propertyId: string; unitId: string; tenantId: string; startDate: string; endDate: string; monthlyRent: number; status: 'active' | 'pending' | 'terminated'; }
interface WorkOrder { id: string; propertyId: string; unitId: string; category: 'plumbing' | 'electrical' | 'hvac' | 'general'; status: string; assignedVendor: string; }
Consideraciones de Escalado
- Partitione los trabajadores de sincronización por región de propiedad para evitar límites de tasa de API entre regiones
- Use réplicas de solo lectura para consultas de dashboard; la ruta de escritura pasa por el pipeline de eventos
- Agrupe las notificaciones a inquilinos (recordatorios de alquiler, actualizaciones de mantenimiento) a través de la cola para evitar límites de tasa de correo electrónico
- Almacene en caché los datos de vacantes de forma agresiva: los agentes de arrendamiento acceden a este endpoint 10 veces más que a cualquier otro
- Fragmente el enrutamiento de órdenes de trabajo por cartera de propiedades para permitir un escalado independiente por grupo de gestión
Manejo de Errores
| Componente | Modo de Fallo | Recuperación |
|---|---|---|
| Sincronización de propiedades | Límite de tasa 429 de AppFolio | Retroceso exponencial con fluctuación, interruptor de circuito por propiedad |
| Webhook de arrendamiento | Entrega de evento duplicado | Clave de idempotencia en ID de arrendamiento + marca de tiempo del evento |
| Enrutamiento de orden de trabajo | Tiempo de espera de API del proveedor | Reintento en cola con respaldo a asignación manual |
| Sincronización contable | Desajuste de saldos | Cola de conciliación con bandera de revisión humana |
| Portal del inquilino | Tormenta de fallos de caché | Patrón obsoleto-mientras-revalida, interruptor de circuito en capa de API |
Salida
- Una arquitectura escalonada con límites de contrato, con servicio, caché, cola, datos y propiedad de conciliación explícitamente separados
- Referencias de dashboard minimizadas y límites cifrados/controlados para datos de contacto, pago y saldo de inquilinos
- Una decisión de implementación respaldada por evidencia de fallo en staging, duplicación/reproducción, tasa, reversión y conciliación
Ejemplos
Para un despliegue de dashboard de vacantes, comience con IDs de propiedad y unidad sintéticos,
una lectura segura acotada y una caché que exponga la antigüedad de los datos. Inyecte un evento duplicado
o registro de conciliación, un 429 y un tiempo de espera contable posterior
para probar que la cola y el almacén de idempotencia evitan efectos duplicados. Promocione
solo cuando los resultados permanezcan completos y autorizados y los propietarios de reversión/conciliación
puedan demostrar sus rutas. Si el soporte de eventos, la clasificación de datos, el estado duradero
o un resultado de escritura no están verificados, mantenga la ruta correspondiente deshabilitada
y use conciliación dirigida por operador.
Recursos
Próximos Pasos
Consulte appfolio-deploy-integration.