Communitygithub.com

Arquitetura de Referência AppFolio

Arquitetura de referência para integração com o sistema de gerenciamento de propriedades AppFolio.

O que é Arquitetura de Referência AppFolio?

Este skill fornece uma arquitetura de produção completa para integrar sistemas de gerenciamento de propriedades com a API AppFolio Stack. Projetado para portfólios multi-propriedade, ele aborda rastreamento de vagas em tempo real, ciclo de vida de inquilinos, roteamento de ordens de serviço e reconciliação contábil. O skill enfatiza a importância de um contrato verificado pelo provedor, ambientes de staging e produção separados com segredos gerenciados, e uma estratégia de armazenamento em cache que prioriza a precisão financeira e a capacidade de resposta do portal do inquilino. Ele inclui instruções passo a passo, diagramas de arquitetura, trechos de código para a camada de serviço, pipeline de eventos e modelo de dados, além de considerações de escalabilidade e tratamento de erros. O objetivo final é uma implantação controlada por contrato que separa claramente as responsabilidades de serviço, cache, fila, dados e reconciliação, com limites criptografados para dados sensíveis do inquilino.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-reference-architecture

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Arquitetura de Referência AppFolio faz?

Visão Geral

Arquitetura de produção para integrações de gerenciamento de propriedades com a API AppFolio Stack. Projetada para portfólios multi-propriedade que exigem rastreamento de vagas em tempo real, gerenciamento do ciclo de vida de inquilinos, roteamento de ordens de serviço e reconciliação contábil. Direcionadores de design principais: frescor dos dados para decisões de locação, sincronização idempotente para precisão financeira e capacidade de resposta do portal do inquilino.

Pré-requisitos

  • Um contrato verificado pelo provedor para endpoints, autenticação, eventos (se houver), limites de taxa, residência de dados e efeitos contábeis/CRM downstream permitidos.
  • Ambientes de staging e produção separados com segredos gerenciados, fixtures sintéticas, filas/armazenamentos de idempotência duráveis e proprietários de reconciliação nomeados.
  • Classificação de dados que limita os modelos de dashboard e cache aos menores campos permitidos; dados de contato, pagamento e saldo do inquilino exigem armazenamentos criptografados e controles de acesso separados.

Instruções

  1. Construa primeiro a camada de serviço cliente e de leitura segura vinculada ao contrato, com orçamentos de endpoint, entradas de cache minimizadas e observabilidade antes de adicionar processamento de gravação ou eventos.
  2. Habilite eventos do provedor somente após o contrato e os limites de corpo bruto durável, assinatura, persistência e reprodução terem sido comprovados; caso contrário, use reconciliação incremental limitada.
  3. Persista um registro de idempotência/reconciliação antes de qualquer mutação de ordem de serviço, contábil, inquilino ou locação e exija autorização explícita.
  4. Valide a arquitetura em staging com dados sintéticos, uma falha forçada do provedor, evento duplicado/repetição e um ensaio de reversão antes da promoção.

Diagrama da Arquitetura

Dashboard (React) ──→ Serviço de Propriedade ──→ Cache Redis ──→ API AppFolio Stack
                           ↓                                 /properties
                      Fila (Bull) ──→ Worker de Sincronização           /tenants
                           ↓                                 /leases
                      Manipulador de Eventos ←── Eventos do provedor*      /work-orders
                           ↓                                 /bills
                      Sincronização Contábil ──→ QuickBooks/Xero

* Use eventos do provedor somente quando o contrato ativo confirmar sua entrega e semânticas de segurança; caso contrário, alimente a fila a partir de reconciliação limitada.

Camada de Serviço

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

Estratégia de Cache

const CACHE_CONFIG = {
  properties: { ttl: 300, prefix: 'prop' },     // 5 min — muda com pouca frequência
  tenants:    { ttl: 120, prefix: 'tenant' },    // 2 min — rotatividade moderada
  leases:     { ttl: 60,  prefix: 'lease' },     // 1 min — precisão financeira
  workOrders: { ttl: 30,  prefix: 'wo' },        // 30s — rastreamento em tempo real
  vacancies:  { ttl: 15,  prefix: 'vacancy' },   // 15s — velocidade de locação é importante
};
// Invalidação orientada por webhook: eventos AppFolio liberam as chaves de cache correspondentes imediatamente

Pipeline de Eventos

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

Modelo de Dados

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

Considerações de Escalabilidade

  • Particione workers de sincronização por região de propriedade para evitar limites de taxa de API entre regiões
  • Use réplicas de leitura para consultas do dashboard; o caminho de gravação passa pelo pipeline de eventos
  • Agrupe notificações de inquilinos (lembretes de aluguel, atualizações de manutenção) via fila para evitar limites de taxa de e-mail
  • Armazene dados de vagas em cache agressivamente — agentes de locação acessam este endpoint 10x mais do que qualquer outro
  • Fragmente o roteamento de ordens de serviço por portfólio de propriedade para permitir escalonamento independente por grupo de gerenciamento

Tratamento de Erros

ComponenteModo de FalhaRecuperação
Sincronização de propriedadeLimite de taxa AppFolio 429Backoff exponencial com jitter, disjuntor por propriedade
Webhook de locaçãoEntrega de evento duplicadaChave de idempotência no ID da locação + timestamp do evento
Roteamento de ordem de serviçoTimeout da API do fornecedorRepetição em fila com fallback para atribuição manual
Sincronização contábilDiscrepância de saldoFila de reconciliação com sinalizador de revisão humana
Portal do inquilinoTempestade de falhas de cachePadrão stale-while-revalidate, disjuntor na camada de API

Saída

  • Uma arquitetura vinculada a contrato e em estágios, com serviço, cache, fila, dados e proprietários de reconciliação explicitamente separados
  • Referências de dashboard minimizadas e limites criptografados/controlados para dados de contato, pagamento e saldo do inquilino
  • Uma decisão de implantação apoiada por evidências de falha em staging, duplicação/repetição, taxa, reversão e reconciliação

Exemplos

Para uma implantação de dashboard de vagas, comece com IDs de propriedade e unidade sintéticos, uma leitura segura limitada e um cache que expõe a idade dos dados. Injete um evento duplicado ou registro de reconciliação, um 429 e um timeout contábil downstream para provar que a fila e o armazenamento de idempotência impedem efeitos duplicados. Promova somente quando os resultados permanecerem completos e autorizados e os proprietários de reversão/reconciliação puderem demonstrar seus caminhos. Se o suporte a eventos, classificação de dados, estado durável ou um resultado de gravação não for verificado, mantenha o caminho correspondente desabilitado e use reconciliação liderada pelo operador.

Recursos

Próximos Passos

Veja appfolio-deploy-integration.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Diagnose and fix common AppFolio API integration errors. Trigger: "appfolio error".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Handle AppFolio API rate limits with throttling and backoff. Trigger: "appfolio rate limit".

jeremylongshore/tons-of-skills-marketplace

Apply production-ready patterns for AppFolio REST API integration. Trigger: "appfolio patterns".

Habilidades Relacionadas