Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/appfolio-pack/skills/appfolio-reference-architecture/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill appfolio-reference-architecture. Copyright stays with the author (MIT).

AppFolio Reference Architecture

Overview

Production architecture for property management integrations with the AppFolio Stack API. Designed for multi-property portfolios requiring real-time vacancy tracking, tenant lifecycle management, work order routing, and accounting reconciliation. Key design drivers: data freshness for leasing decisions, idempotent sync for financial accuracy, and tenant-facing portal responsiveness.

Prerequisites

• A provider-verified contract for endpoints, authentication, events (if any), rate limits, data residency, and permitted downstream accounting/CRM effects.
• Separate staging and production environments with managed secrets, synthetic fixtures, durable queues/idempotency stores, and named reconciliation owners.
• Data classification that limits dashboard and cache models to the smallest permitted fields; tenant contact, payment, and balance data require separate encrypted stores and access controls.

Instructions

1. Build the contract-bound client and safe-read service layer first, with endpoint budgets, minimized cache entries, and observability before adding write or event processing.
2. Enable provider events only after the contract and durable raw-body, signature, persistence, and replay boundaries have been proven; otherwise use bounded incremental reconciliation.
3. Persist an idempotency/reconciliation record before any work-order, accounting, tenant, or lease mutation and require explicit authorization.
4. Validate the architecture in staging with synthetic data, a forced provider failure, duplicate event/retry, and rollback rehearsal before promotion.

Architecture Diagram

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

* Use provider events only when the active contract confirms their delivery and security semantics; otherwise feed the queue from bounded reconciliation.

Service Layer

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 Strategy

const CACHE_CONFIG = {
  properties: { ttl: 300, prefix: 'prop' },     // 5 min — changes infrequently
  tenants:    { ttl: 120, prefix: 'tenant' },    // 2 min — moderate churn
  leases:     { ttl: 60,  prefix: 'lease' },     // 1 min — financial accuracy
  workOrders: { ttl: 30,  prefix: 'wo' },        // 30s — real-time tracking
  vacancies:  { ttl: 15,  prefix: 'vacancy' },   // 15s — leasing speed matters
};
// Webhook-driven invalidation: AppFolio events flush matching cache keys immediately

Event Pipeline

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);
  }
}

Data Model

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; }

Scaling Considerations

• Partition sync workers by property region to avoid cross-region API rate limits
• Use read replicas for dashboard queries; write path goes through event pipeline
• Batch tenant notifications (rent reminders, maintenance updates) via queue to avoid email rate limits
• Cache vacancy data aggressively — leasing agents hit this endpoint 10x more than any other
• Shard work order routing by property portfolio to enable independent scaling per management group

Error Handling

Output

• A contract-bound, staged architecture with service, cache, queue, data, and reconciliation ownership explicitly separated
• Minimized dashboard references and encrypted/controlled boundaries for tenant contact, payment, and balance data
• A deployment decision supported by staging failure, duplicate/replay, rate, rollback, and reconciliation evidence

Examples

For a vacancy-dashboard rollout, start with synthetic property and unit IDs, one bounded safe-read, and a cache that exposes data age. Inject a duplicate event or reconciliation record, a 429, and a downstream accounting timeout to prove the queue and idempotency store prevent duplicate effects. Promote only when results remain complete and authorized and the rollback/reconciliation owners can demonstrate their paths. If event support, data classification, durable state, or a write outcome is unverified, keep the corresponding path disabled and use operator-led reconciliation.

Resources

• AppFolio Stack APIs
• AppFolio Engineering Blog

Next Steps

See appfolio-deploy-integration.