AppFolio Referenzarchitektur
Überblick
Produktionsarchitektur für Immobilienverwaltungsintegrationen mit der AppFolio Stack API. Konzipiert für Multi-Property-Portfolios, die eine Echtzeit-Verfolgung von Leerständen, Verwaltung des Mieterlebenszyklus, Weiterleitung von Arbeitsaufträgen und buchhalterische Abstimmung erfordern. Wichtigste Entwurfstreiber: Datenaktualität für Leasingentscheidungen, idempotente Synchronisation für finanzielle Genauigkeit und Reaktionsfähigkeit des Mieterportals.
Voraussetzungen
- Ein vom Anbieter bestätigter Vertrag über Endpunkte, Authentifizierung, Ereignisse (falls vorhanden), Ratennutzungsgrenzen, Datenresidenz und zulässige nachgelagerte Auswirkungen auf Buchhaltung/CRM.
- Separate Staging- und Produktionsumgebungen mit verwalteten Geheimnissen, synthetischen Testdaten, langlebigen Warteschlangen/Idempotenzspeichern und benannten Abstimmungsverantwortlichen.
- Datenklassifizierung, die Dashboard- und Cache-Modelle auf die kleinstmöglichen zulässigen Felder beschränkt; Mieterkontakt-, Zahlungs- und Saldodaten erfordern separate verschlüsselte Speicher und Zugriffskontrollen.
Anleitung
- Bauen Sie zuerst die vertragsgebundene Client- und schreibgeschützte Dienstebene auf, mit Endpunktbudgets, minimierten Cache-Einträgen und Beobachtbarkeit, bevor Sie Schreib- oder Ereignisverarbeitung hinzufügen.
- Aktivieren Sie Anbieterereignisse erst, wenn der Vertrag und die dauerhaften Rohdaten-, Signatur-, Persistenz- und Wiederholungsgrenzen nachgewiesen wurden; verwenden Sie andernfalls eine begrenzte inkrementelle Abstimmung.
- Persistieren Sie einen Idempotenz-/Abstimmungsdatensatz, bevor Sie eine Mutation von Arbeitsaufträgen, Buchhaltungs-, Mieter- oder Leasingdaten durchführen, und fordern Sie eine explizite Autorisierung.
- Validieren Sie die Architektur im Staging mit synthetischen Daten, einem erzwungenen Anbieterfehler, einem doppelten Ereignis/Wiederholungsversuch und einer Rollback-Übung vor der Übernahme.
Architekturdiagramm
Dashboard (React) ──→ Property Service ──→ Redis Cache ──→ AppFolio Stack API
↓ /properties
Queue (Bull) ──→ Sync Worker /tenants
↓ /leases
Event Handler ←── Provider events* /work-orders
↓ /bills
Accounting Sync ──→ QuickBooks/Xero
* Verwenden Sie Anbieterereignisse nur, wenn der aktive Vertrag deren Zustellung und Sicherheitssemantik bestätigt; andernfalls speisen Sie die Warteschlange aus der begrenzten Abstimmung.
Dienstebene
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 });
}
}
Caching-Strategie
const CACHE_CONFIG = {
properties: { ttl: 300, prefix: 'prop' }, // 5 min — seltene Änderungen
tenants: { ttl: 120, prefix: 'tenant' }, // 2 min — moderate Änderungen
leases: { ttl: 60, prefix: 'lease' }, // 1 min — finanzielle Genauigkeit
workOrders: { ttl: 30, prefix: 'wo' }, // 30s — Echtzeitverfolgung
vacancies: { ttl: 15, prefix: 'vacancy' }, // 15s — Leerstandsgeschwindigkeit ist wichtig
};
// Webhook-basierte Invalidierung: AppFolio-Ereignisse leeren sofort entsprechende Cache-Schlüssel
Ereignispipeline
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);
}
}
Datenmodell
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; }
Skalierungsüberlegungen
- Partitionieren Sie Sync-Worker nach Immobilienregion, um regionsübergreifende API-Ratenbegrenzungen zu vermeiden.
- Verwenden Sie Lesereplikate für Dashboard-Abfragen; der Schreibpfad verläuft über die Ereignispipeline.
- Bündeln Sie Mieterbenachrichtigungen (Mietzahlungserinnerungen, Wartungsupdates) über die Warteschlange, um E-Mail-Ratenbegrenzungen zu vermeiden.
- Cachen Sie Leerstandsdaten aggressiv – Leasing-Agenten greifen auf diesen Endpunkt 10x häufiger zu als auf andere.
- Sharding der Arbeitsauftragsrouting nach Immobilienportfolio, um unabhängige Skalierung pro Verwaltungsgruppe zu ermöglichen.
Fehlerbehandlung
| Komponente | Fehlermodus | Wiederherstellung |
|---|---|---|
| Immobiliensynchronisation | AppFolio 429 Ratenbegrenzung | Exponentielles Backoff mit Jitter, leerstandsabhängiger Schutzschalter |
| Leasing-Webhook | Doppelte Ereigniszustellung | Idempotenzschlüssel auf Leasing-ID + Ereigniszeitstempel |
| Arbeitsauftragsrouting | Zeitüberschreitung der Anbieter-API | Warteschlangenwiederholung mit Rückfall auf manuelle Zuordnung |
| Buchhaltungssynchronisation | Saldenabweichung | Abstimmungswarteschlange mit manuellem Prüfungsflag |
| Mieterportal | Cache-Fehlerschwall | Stale-while-revalidate-Muster, Schutzschalter auf API-Ebene |
Ausgabe
- Eine vertragsgebundene, gestufte Architektur mit Service, Cache, Warteschlange, Daten und klar getrennter Abstimmungsverantwortung.
- Minimierte Dashboard-Referenzen und verschlüsselte/kontrollierte Grenzen für Mieterkontakt-, Zahlungs- und Saldodaten.
- Eine durch Staging-Fehler, Duplikate/Wiederholungen, Raten, Rollback und Abstimmungsnachweise gestützte Bereitstellungsentscheidung.
Beispiele
Für einen Leerstands-Dashboard-Rollout beginnen Sie mit synthetischen Immobilien- und Einheiten-IDs, einem begrenzten schreibgeschützten Zugriff und einem Cache, der das Datenalter anzeigt. Injizieren Sie ein doppeltes Ereignis oder einen Abstimmungsdatensatz, einen 429-Fehler und eine nachgelagerte Buchhaltungs-Zeitüberschreitung, um zu beweisen, dass die Warteschlange und der Idempotenzspeicher doppelte Effekte verhindern. Übernehmen Sie die Änderungen erst, wenn die Ergebnisse vollständig und autorisiert bleiben und die Rollback-/Abstimmungsverantwortlichen ihre Pfade nachweisen können. Wenn Ereignisunterstützung, Datenklassifizierung, dauerhafter Zustand oder ein Schreibergebnis nicht verifiziert sind, halten Sie den entsprechenden Pfad deaktiviert und verwenden Sie eine betreibergeführte Abstimmung.
Ressourcen
Nächste Schritte
Siehe appfolio-deploy-integration.