AppFolio 참조 아키텍처
개요
AppFolio Stack API를 사용한 부동산 관리 통합을 위한 프로덕션 아키텍처입니다. 실시간 공실 추적, 임차인 라이프사이클 관리, 작업 지시 라우팅, 회계 조정이 필요한 다중 부동산 포트폴리오를 대상으로 설계되었습니다. 주요 설계 동기는 임대 결정을 위한 데이터 신선도, 재무 정확성을 위한 멱등 동기화, 임차인 포털 응답성입니다.
전제 조건
- 엔드포인트, 인증, 이벤트(있는 경우), 속도 제한, 데이터 상주, 허용된 다운스트림 회계/CRM 효과에 대한 공급자 검증 계약
- 관리되는 시크릿, 합성 픽스처, 내구성 있는 큐/멱등성 저장소, 명명된 조정 소유자가 있는 별도의 스테이징 및 프로덕션 환경
- 대시보드 및 캐시 모델을 허용된 최소 필드로 제한하는 데이터 분류; 임차인 연락처, 결제 및 잔액 데이터는 별도의 암호화된 저장소와 액세스 제어 필요
지침
- 먼저 계약에 바인딩된 클라이언트와 안전한 읽기 서비스 계층을 구축합니다. 엔드포인트 예산, 최소화된 캐시 항목, 관찰 가능성을 확보한 후 쓰기 또는 이벤트 처리를 추가합니다.
- 계약과 내구성 있는 원시 본문, 서명, 지속성, 재생 경계가 입증된 경우에만 공급자 이벤트를 활성화합니다. 그렇지 않으면 제한된 증분 조정을 사용합니다.
- 작업 지시, 회계, 임차인 또는 임대 변경 전에 멱등성/조정 레코드를 유지하고 명시적 승인을 요구합니다.
- 프로덕션 승격 전에 합성 데이터, 강제 공급자 장애, 중복 이벤트/재시도, 롤백 리허설을 통해 스테이징에서 아키텍처를 검증합니다.
아키텍처 다이어그램
대시보드 (React) ──→ 부동산 서비스 ──→ Redis 캐시 ──→ AppFolio Stack API
↓ /properties
큐 (Bull) ──→ 동기화 워커 /tenants
↓ /leases
이벤트 핸들러 ←── 공급자 이벤트* /work-orders
↓ /bills
회계 동기화 ──→ 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초 — 임대 속도 중요
};
// 웹훅 기반 무효화: 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 속도 제한 | 지수 백오프 및 지터, 부동산별 회로 차단기 |
| 임대 웹훅 | 중복 이벤트 전달 | 임대 ID + 이벤트 타임스탬프의 멱등성 키 |
| 작업 지시 라우팅 | 공급업체 API 시간 초과 | 수동 할당 대체를 통한 큐 재시도 |
| 회계 동기화 | 잔액 불일치 | 사람 검토 플래그가 있는 조정 큐 |
| 임차인 포털 | 캐시 미스 폭주 | Stale-while-revalidate 패턴, API 계층의 회로 차단기 |
출력
- 서비스, 캐시, 큐, 데이터 및 조정 소유권이 명시적으로 분리된 계약 기반의 단계별 아키텍처
- 최소화된 대시보드 참조 및 임차인 연락처, 결제, 잔액 데이터에 대한 암호화/제어 경계
- 스테이징 장애, 중복/재생, 속도, 롤백 및 조정 증거로 뒷받침되는 배포 결정
예시
공실 대시보드 롤아웃의 경우 합성 부동산 및 단위 ID, 하나의 제한된 안전 읽기, 데이터 사용 기간을 노출하는 캐시로 시작합니다. 중복 이벤트 또는 조정 레코드, 429, 다운스트림 회계 시간 초과를 주입하여 큐와 멱등성 저장소가 중복 효과를 방지하는지 입증합니다. 결과가 완전하고 승인된 상태로 유지되고 롤백/조정 소유자가 자신의 경로를 시연할 수 있는 경우에만 승격합니다. 이벤트 지원, 데이터 분류, 내구성 있는 상태 또는 쓰기 결과가 확인되지 않은 경우 해당 경로를 비활성화된 상태로 유지하고 운영자 주도 조정을 사용합니다.
리소스
다음 단계
appfolio-deploy-integration을 참조하세요.