AppFolio リファレンスアーキテクチャ は何をしますか?
概要
AppFolio Stack API との物件管理統合のためのプロダクション向けアーキテクチャです。複数物件ポートフォリオにおけるリアルタイム空室追跡、テナントライフサイクル管理、作業指示ルーティング、会計調整を目的として設計されています。主要な設計目標は、リース判断のためのデータ鮮度、財務精度のための冪等同期、テナント向けポータルの応答性です。
前提条件
- エンドポイント、認証、イベント(存在する場合)、レート制限、データ所在地、許可された下流の会計/CRM への影響について、プロバイダーが確認した契約が必要です。
- ステージング環境とプロダクション環境は分離し、管理されたシークレット、合成フィクスチャ、耐久性のあるキュー/冪等性ストア、指名された調整責任者を用意してください。
- ダッシュボードとキャッシュモデルを最小限の許可フィールドに制限するデータ分類を実施してください。テナントの連絡先、支払い、残高データには、別の暗号化ストアとアクセス制御が必要です。
手順
- 最初に、エンドポイント予算、最小限のキャッシュエントリ、および観測可能性を備えた、契約に基づくクライアントと安全読み取りサービスのレイヤーを構築します。書き込みやイベント処理は後回しにします。
- プロバイダーイベントは、契約と耐久性のある生本文、署名、永続化、リプレイ境界が証明された後にのみ有効にします。それ以外の場合は、境界のあるインクリメンタル調整を使用します。
- 作業指示、会計、テナント、リースのミューテーションの前に、冪等性/調整レコードを永続化し、明示的な許可を要求します。
- プロモーションの前に、合成データを使用したステージング環境でのアーキテクチャ検証、強制的なプロバイダー障害の注入、重複イベント/リトライのテスト、ロールバックリハーサルを実施します。
アーキテクチャ図
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
* プロバイダーイベントは、アクティブな契約がその配信とセキュリティセマンティクスを確認している場合にのみ使用します。それ以外の場合は、境界のある調整からのキューを使用します。
サービスのレイヤー
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 });
}
}
キャッシュ戦略
const CACHE_CONFIG = {
properties: { ttl: 300, prefix: 'prop' }, // 5分 — 頻繁には変更されない
tenants: { ttl: 120, prefix: 'tenant' }, // 2分 — 中程度の変動
leases: { ttl: 60, prefix: 'lease' }, // 1分 — 財務精度
workOrders: { ttl: 30, prefix: 'wo' }, // 30秒 — リアルタイム追跡
vacancies: { ttl: 15, prefix: 'vacancy' }, // 15秒 — リーススピードが重要
};
// Webhook駆動の無効化: AppFolioイベントは一致するキャッシュキーを即座にフラッシュ
イベントパイプライン
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);
}
}
データモデル
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; }
スケーリングに関する考慮事項
- 同期ワーカーを物件リージョンごとに分割して、リージョン間のAPIレート制限を回避します。
- ダッシュボードクエリには読み取りレプリカを使用します。書き込みパスはイベントパイプラインを通ります。
- テナントへの通知(家賃リマインダー、メンテナンス更新)はキューを介してバッチ処理し、メールのレート制限を回避します。
- 空室データは積極的にキャッシュします。リース担当者はこのエンドポイントを他のどのエンドポイントよりも10倍多くヒットします。
- 作業指示ルーティングを物件ポートフォリオごとにシャーディングして、管理グループごとの独立したスケーリングを可能にします。
エラーハンドリング
| コンポーネント | 障害モード | 回復方法 |
|---|---|---|
| プロパティ同期 | AppFolio 429 レート制限 | 指数バックオフ(ジッター付き)、物件別サーキットブレーカー |
| リースWebhook | 重複イベント配信 | リースID + イベントタイムスタンプによる冪等性キー |
| 作業指示ルーティング | ベンダーAPIタイムアウト | キューリトライ、フォールバックとして手動割り当て |
| 会計同期 | 残高不一致 | 人間によるレビューフラグ付き調整キュー |
| テナントポータル | キャッシュミスストーム | stale-while-revalidate パターン、APIレイヤーのサーキットブレーカー |
出力
- サービス、キャッシュ、キュー、データ、調整責任が明示的に分離された、契約に基づく段階的なアーキテクチャ。
- 最小化されたダッシュボード参照、およびテナントの連絡先、支払い、残高データの暗号化/制御された境界。
- ステージングでの障害、重複/リプレイ、レート、ロールバック、調整のエビデンスによってサポートされたデプロイ決定。
例
空室ダッシュボードのロールアウトでは、合成のプロパティIDとユニットID、1つの境界のある安全な読み取り、データの経過時間を公開するキャッシュから始めます。重複イベントまたは調整レコード、429、および下流の会計タイムアウトを注入して、キューと冪等性ストアが重複効果を防止することを証明します。結果が完全で許可されたままであり、ロールバック/調整責任者がそのパスを実証できる場合にのみプロモーションします。イベントサポート、データ分類、耐久性のある状態、または書き込み結果が未検証の場合は、対応するパスを無効にしたままにし、オペレーター主導の調整を使用します。
リソース
次のステップ
appfolio-deploy-integration を参照してください。