Skip to main content

Architecture Overview

AsaHome Cloud is designed as a secure, scalable relay service that bridges Flutter mobile applications with AsaHome OS home automation devices.

System Architecture​

Component Responsibilities​

Nginx Reverse Proxy​

The entry point for all traffic, handling:

  • TLS Termination: Encrypts all traffic with SSL/TLS
  • Load Balancing: Distributes traffic across multiple app instances
  • Security Headers: Injects HSTS, CSP, X-Frame-Options
  • WebSocket Upgrade: Handles HTTP to WebSocket protocol upgrade
  • Rate Limiting: Throttles requests per IP address
  • Static Assets: Serves static files efficiently

NestJS Application​

The main business logic layer:

ModuleResponsibility
AuthModuleJWT authentication, token refresh, logout
UsersModuleUser profile management
DevicesModuleDevice registration, linking, heartbeat
CustomersModuleLaravel customer sync integration
WebSocketModuleReal-time tunnel gateway

WebSocket Gateway​

Handles real-time bidirectional communication:

PostgreSQL Database​

Stores all persistent data:

  • Users: Account information, credentials, roles
  • Devices: Registered AsaHome OS devices
  • Device Users: Many-to-many user-device relationships
  • Refresh Tokens: Hashed tokens for session management
  • Audit Logs: Security and activity logging

Data Flow​

Authentication Flow​

Device Command Flow​

Scalability Considerations​

Horizontal Scaling​

The architecture supports horizontal scaling:

WebSocket Sticky Sessions​

For WebSocket connections, sticky sessions ensure clients reconnect to the same instance:

  • Device connections maintain persistent tunnel
  • User connections can be stateless with Redis pub/sub (future enhancement)

Database Connection Pooling​

TypeORM connection pooling optimizes database connections:

// Connection pool configuration
{
  type: 'postgres',
  extra: {
    max: 20,           // Maximum connections
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  }
}

Security Layers​

See Security Guide for detailed security documentation.

Next Steps​