Architecture de Référence AppFolio
Vue d'ensemble
Architecture de production pour les intégrations de gestion immobilière avec l'API AppFolio Stack. Conçue pour les portefeuilles multi-propriétés nécessitant un suivi en temps réel des vacances, la gestion du cycle de vie des locataires, le routage des ordres de travail et la réconciliation comptable. Principaux axes de conception : fraîcheur des données pour les décisions de location, synchronisation idempotente pour la précision financière et réactivité du portail locataire.
Prérequis
- Un contrat vérifié par le fournisseur pour les points d'accès, l'authentification, les événements (le cas échéant), les limites de débit, la résidence des données et les effets comptables/CRM en aval autorisés.
- Des environnements de staging et de production séparés avec des secrets gérés, des fixtures synthétiques, des files d'attente/magasins d'idempotence durables et des propriétaires de réconciliation nommés.
- Une classification des données qui limite les modèles de tableaux de bord et de cache aux plus petits champs autorisés ; les données de contact, de paiement et de solde des locataires nécessitent des magasins cryptés et des contrôles d'accès séparés.
Instructions
- Construire d'abord le client lié au contrat et la couche de service en lecture sécurisée, avec des budgets de points d'accès, des entrées de cache minimisées et une observabilité avant d'ajouter l'écriture ou le traitement d'événements.
- Activer les événements du fournisseur uniquement après avoir prouvé les limites du contrat et du corps brut durable, de la signature, de la persistance et de la relecture ; sinon utiliser une réconciliation incrémentielle bornée.
- Persister un enregistrement d'idempotence/réconciliation avant toute mutation d'ordre de travail, comptable, de locataire ou de bail et nécessiter une autorisation explicite.
- Valider l'architecture en staging avec des données synthétiques, une panne forcée du fournisseur, un événement/une tentative en double et une répétition de rollback avant la promotion.
Diagramme d'architecture
Tableau de bord (React) ──→ Service Immobilier ──→ Cache Redis ──→ API AppFolio Stack
↓ /properties
File (Bull) ──→ Worker de Sync /tenants
↓ /leases
Gestionnaire d'événements ←── Événements fournisseur* /work-orders
↓ /bills
Sync Comptable ──→ QuickBooks/Xero
* Utiliser les événements fournisseur uniquement lorsque le contrat actif confirme leur livraison et leur sémantique de sécurité ; sinon alimenter la file d'attente à partir d'une réconciliation bornée.
Couche de service
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 });
}
}
Stratégie de cache
const CACHE_CONFIG = {
properties: { ttl: 300, prefix: 'prop' }, // 5 min — change peu fréquemment
tenants: { ttl: 120, prefix: 'tenant' }, // 2 min — rotation modérée
leases: { ttl: 60, prefix: 'lease' }, // 1 min — précision financière
workOrders: { ttl: 30, prefix: 'wo' }, // 30s — suivi en temps réel
vacancies: { ttl: 15, prefix: 'vacancy' }, // 15s — la vitesse de location est importante
};
// Invalidation pilotée par webhook : les événements AppFolio vident immédiatement les clés de cache correspondantes
Pipeline d'événements
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);
}
}
Modèle de données
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; }
Considérations de passage à l'échelle
- Partitionner les workers de synchronisation par région de propriété pour éviter les limites de débit API inter-régions
- Utiliser des réplicas en lecture pour les requêtes du tableau de bord ; le chemin d'écriture passe par le pipeline d'événements
- Regrouper les notifications des locataires (rappels de loyer, mises à jour de maintenance) via une file d'attente pour éviter les limites de débit des e-mails
- Mettre en cache agressivement les données de vacance — les agents de location accèdent à ce point d'accès 10 fois plus qu'à tout autre
- Fragmenter le routage des ordres de travail par portefeuille de propriétés pour permettre une mise à l'échelle indépendante par groupe de gestion
Gestion des erreurs
| Composant | Mode de panne | Récupération |
|---|---|---|
| Synchronisation des propriétés | Limite de débit AppFolio 429 | Backoff exponentiel avec gigue, disjoncteur par propriété |
| Webhook de bail | Livraison d'événements en double | Clé d'idempotence sur ID de bail + horodatage de l'événement |
| Routage des ordres de travail | Délai d'attente de l'API fournisseur | Nouvelle tentative de file d'attente avec basculement vers une affectation manuelle |
| Synchronisation comptable | Écart de solde | File de réconciliation avec indicateur de révision humaine |
| Portail locataire | Tempête de ratés du cache | Motif stale-while-revalidate, disjoncteur sur couche API |
Résultat
- Une architecture liée par contrat et par étapes, avec service, cache, file d'attente, données et propriété de réconciliation explicitement séparés
- Des références de tableau de bord minimisées et des limites cryptées/contrôlées pour les données de contact, de paiement et de solde des locataires
- Une décision de déploiement soutenue par des preuves de panne en staging, de duplication/relecture, de débit, de rollback et de réconciliation
Exemples
Pour un déploiement de tableau de bord des vacances, commencez avec des ID de propriété et d'unité synthétiques, une lecture sécurisée bornée et un cache qui expose l'âge des données. Injectez un événement en double ou un enregistrement de réconciliation, un 429 et un délai d'attente comptable en aval pour prouver que la file d'attente et le magasin d'idempotence empêchent les effets en double. Promouvez uniquement lorsque les résultats restent complets et autorisés et que les propriétaires du rollback/de la réconciliation peuvent démontrer leurs chemins. Si le support des événements, la classification des données, l'état durable ou un résultat d'écriture n'est pas vérifié, gardez le chemin correspondant désactivé et utilisez une réconciliation dirigée par l'opérateur.
Ressources
Prochaines étapes
Voir appfolio-deploy-integration.