O que Arquitetura de Referência AppFolio faz?
Visão Geral
Arquitetura de produção para integrações de gerenciamento de propriedades com a API AppFolio Stack. Projetada para portfólios multi-propriedade que exigem rastreamento de vagas em tempo real, gerenciamento do ciclo de vida de inquilinos, roteamento de ordens de serviço e reconciliação contábil. Direcionadores de design principais: frescor dos dados para decisões de locação, sincronização idempotente para precisão financeira e capacidade de resposta do portal do inquilino.
Pré-requisitos
- Um contrato verificado pelo provedor para endpoints, autenticação, eventos (se houver), limites de taxa, residência de dados e efeitos contábeis/CRM downstream permitidos.
- Ambientes de staging e produção separados com segredos gerenciados, fixtures sintéticas, filas/armazenamentos de idempotência duráveis e proprietários de reconciliação nomeados.
- Classificação de dados que limita os modelos de dashboard e cache aos menores campos permitidos; dados de contato, pagamento e saldo do inquilino exigem armazenamentos criptografados e controles de acesso separados.
Instruções
- Construa primeiro a camada de serviço cliente e de leitura segura vinculada ao contrato, com orçamentos de endpoint, entradas de cache minimizadas e observabilidade antes de adicionar processamento de gravação ou eventos.
- Habilite eventos do provedor somente após o contrato e os limites de corpo bruto durável, assinatura, persistência e reprodução terem sido comprovados; caso contrário, use reconciliação incremental limitada.
- Persista um registro de idempotência/reconciliação antes de qualquer mutação de ordem de serviço, contábil, inquilino ou locação e exija autorização explícita.
- Valide a arquitetura em staging com dados sintéticos, uma falha forçada do provedor, evento duplicado/repetição e um ensaio de reversão antes da promoção.
Diagrama da Arquitetura
Dashboard (React) ──→ Serviço de Propriedade ──→ Cache Redis ──→ API AppFolio Stack
↓ /properties
Fila (Bull) ──→ Worker de Sincronização /tenants
↓ /leases
Manipulador de Eventos ←── Eventos do provedor* /work-orders
↓ /bills
Sincronização Contábil ──→ QuickBooks/Xero
* Use eventos do provedor somente quando o contrato ativo confirmar sua entrega e semânticas de segurança; caso contrário, alimente a fila a partir de reconciliação limitada.
Camada de Serviço
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 });
}
}
Estratégia de Cache
const CACHE_CONFIG = {
properties: { ttl: 300, prefix: 'prop' }, // 5 min — muda com pouca frequência
tenants: { ttl: 120, prefix: 'tenant' }, // 2 min — rotatividade moderada
leases: { ttl: 60, prefix: 'lease' }, // 1 min — precisão financeira
workOrders: { ttl: 30, prefix: 'wo' }, // 30s — rastreamento em tempo real
vacancies: { ttl: 15, prefix: 'vacancy' }, // 15s — velocidade de locação é importante
};
// Invalidação orientada por webhook: eventos AppFolio liberam as chaves de cache correspondentes imediatamente
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 Dados
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; }
Considerações de Escalabilidade
- Particione workers de sincronização por região de propriedade para evitar limites de taxa de API entre regiões
- Use réplicas de leitura para consultas do dashboard; o caminho de gravação passa pelo pipeline de eventos
- Agrupe notificações de inquilinos (lembretes de aluguel, atualizações de manutenção) via fila para evitar limites de taxa de e-mail
- Armazene dados de vagas em cache agressivamente — agentes de locação acessam este endpoint 10x mais do que qualquer outro
- Fragmente o roteamento de ordens de serviço por portfólio de propriedade para permitir escalonamento independente por grupo de gerenciamento
Tratamento de Erros
| Componente | Modo de Falha | Recuperação |
|---|---|---|
| Sincronização de propriedade | Limite de taxa AppFolio 429 | Backoff exponencial com jitter, disjuntor por propriedade |
| Webhook de locação | Entrega de evento duplicada | Chave de idempotência no ID da locação + timestamp do evento |
| Roteamento de ordem de serviço | Timeout da API do fornecedor | Repetição em fila com fallback para atribuição manual |
| Sincronização contábil | Discrepância de saldo | Fila de reconciliação com sinalizador de revisão humana |
| Portal do inquilino | Tempestade de falhas de cache | Padrão stale-while-revalidate, disjuntor na camada de API |
Saída
- Uma arquitetura vinculada a contrato e em estágios, com serviço, cache, fila, dados e proprietários de reconciliação explicitamente separados
- Referências de dashboard minimizadas e limites criptografados/controlados para dados de contato, pagamento e saldo do inquilino
- Uma decisão de implantação apoiada por evidências de falha em staging, duplicação/repetição, taxa, reversão e reconciliação
Exemplos
Para uma implantação de dashboard de vagas, comece com IDs de propriedade e unidade sintéticos, uma leitura segura limitada e um cache que expõe a idade dos dados. Injete um evento duplicado ou registro de reconciliação, um 429 e um timeout contábil downstream para provar que a fila e o armazenamento de idempotência impedem efeitos duplicados. Promova somente quando os resultados permanecerem completos e autorizados e os proprietários de reversão/reconciliação puderem demonstrar seus caminhos. Se o suporte a eventos, classificação de dados, estado durável ou um resultado de gravação não for verificado, mantenha o caminho correspondente desabilitado e use reconciliação liderada pelo operador.
Recursos
Próximos Passos
Veja appfolio-deploy-integration.