Skip to main content

Architecture Overview

This section provides comprehensive documentation of the Broadford Living platform architecture, covering all major systems and design patterns.

System Architecture​

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Clients                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │  Web App    │  │ Mobile App  │  │ SmartThings │  │    Yale     │       │
│  │  (SvelteKit)│  │  (Tauri)    │  │  Webhooks   │  │  Webhooks   │       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘       │
└─────────┼────────────────┼────────────────┼────────────────┼───────────────┘
          │                │                │                │
          ▼                ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Cloudflare Edge                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ bf_resident │  │  bf_auth    │  │  bf_notify  │  │  bf_smart   │       │
│  │   Worker    │  │   Worker    │  │   Worker    │  │   Worker    │       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘       │
│         │                │                │                │               │
│         └────────────────┴────────────────┴────────────────┘               │
│                                   │                                         │
│  ┌────────────────────────────────┼────────────────────────────────────┐   │
│  │                                ▼                                     │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │   │
│  │  │     D1      │  │   Durable   │  │     R2      │  │    KV     │  │   │
│  │  │  Database   │  │   Objects   │  │   Storage   │  │   Cache   │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └───────────┘  │   │
│  │                      Cloudflare Storage                              │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

Documentation Sections​

Core Infrastructure​

The foundational components of the platform:

  • Workers Architecture - Multi-worker design with bf_resident, bf_auth, bf_notify, and bf_smart
  • sqlx-d1 Patterns - Database abstraction for D1 and Durable Object SQLite
  • User Durable Object - Per-property isolated storage with RPC protocol

Authentication​

Security and access control:

  • Clerk Authentication - JWT verification with JWKS rotation
  • Service-to-Service Auth - HMAC-based internal communication
  • Permissions - Role hierarchy and property-based access control

External Integrations​

Smart device platform integrations:

  • Smart Device Abstraction - Unified SmartClient trait across platforms
  • Device Resolution - Matching internal devices to external platform IDs
  • Webhook Handling - Signature verification and event processing

Shared Types​

Cross-crate type definitions:

  • bf_types Library - Shared types for all crates
  • OpenAPI Generation - TypeScript type generation for frontend

Notifications​

Real-time communication:

  • Notification System - FCM push delivery with platform-specific payloads
  • Real-time Events - WebSocket infrastructure and event broadcasting

Property Lifecycle​

Property and tenant management:

  • Property Lifecycle - Status state machine (Setup → Tenancy)
  • Move-In/Move-Out - Tenant transitions and data handling
  • Admin & PM Roles - Portfolio management and access control

IT Setup​

Device commissioning:

  • IT Setup Flow - SmartThings/Yale/Hive configuration
  • Credential Management - Deterministic credential generation

Mobile App​

Tauri-based mobile application:

  • Mobile Architecture - Tauri commands and Clerk SDK
  • OTA Updates - A/B versioning with Ed25519 signatures
  • Client Caching - Asset and credential caching

Security​

Security analysis and practices:

  • Security Audit - Comprehensive security assessment
  • Secret Management - Credential storage and rotation

Key Design Principles​

1. Data Isolation​

Each property has its own Durable Object, ensuring complete isolation of tenant data. No cross-property data access is possible at the storage layer.

2. Platform Abstraction​

The SmartClient trait abstracts away platform differences. Code that controls devices doesn't need to know whether it's talking to SmartThings, Yale, or Hive.

3. Compile-Time Safety​

  • SQL queries are verified at compile time via sqlx
  • Type generation ensures frontend/backend contract alignment
  • Mock mode is compile-time excluded from production builds

4. Event-Driven Architecture​

Webhooks from external platforms are processed asynchronously via queues, enabling reliable event handling without blocking API responses.