System Architecture

1. High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐ ──┐  ┌──────────── ┌──────────────┐  ┌──────────────┐    │
│  │   Web App    │  │  Mobile PWA  │  │ Mobile App   │  │  Admin Panel │    │
│  │   (React)    │  │   (React)    │  │   (Future)   │  │   (React)    │    │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              API GATEWAY                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                     NestJS API Server                                 │   │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐      │   │
│  │  │ REST API    │ │ WebSocket   │ │ Auth/RBAC   │ │ Rate Limit  │      │   │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            SERVICE LAYER                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │    Farm     │ │ Aquaculture │ │   Device    │ │   Report    │           │
│  │   Service   │ │   Service   │ │   Service   │ │   Service   │           │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   Growth    │ │  Daily Log  │ │Notification │ │    User     │           │
│  │   Service   │ │   Service   │ │   Service   │ │   Service   │           │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                            │
│  │  Financial  │ │ Inventory  │ │  Supplier   │                            │
│  │   Service   │ │   Service   │ │   Service   │                            │
│  └─────────────┘ └─────────────┘ └─────────────┘                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                             DATA LAYER                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │     PostgreSQL      │  │       Redis         │  │    File Storage    │  │
│  │  + TimescaleDB     │  │   (Cache/Queue)     │  │    (MinIO/S3)      │  │
│  │  (Business + IoT)   │  │                     │  │                    │  │
│  └─────────────────────┘  └─────────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           IoT LAYER                                          │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                     MQTT Broker (EMQX)                                │   │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐        │   │
│  │  │ Device Auth     │  │ Topic Routing  │  │ Message Queue   │        │   │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘        │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│        ┌───────────────────────────┼───────────────────────────┐            │
│        ▼                           ▼                           ▼            │
│  ┌───────────┐             ┌───────────┐             ┌───────────┐          │
│  │  Sensor   │             │  Gateway  │             │  Sensor   │          │
│  │ (pH,DO..) │             │   (4-IO) │             │ (Future)  │          │
│  └───────────┘             └───────────┘             └───────────┘          │
└─────────────────────────────────────────────────────────────────────────────┘

2. Technology Stack

Layer Technology Purpose
Frontend React 19 + Vite UI framework
UI Lib Ant Design + Tailwind Component library
State TanStack Query + Zustand Data fetching, global state
Backend NestJS API framework
Database PostgreSQL + TimescaleDB Relational + time-series
Cache Redis Session, cache, pub/sub
MQTT EMQX IoT device communication
Storage MinIO File storage (S3-compatible)

3. Deployment Architecture

                    ┌──────────────────┐
                    │   Load Balancer  │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │ Backend 1│   │ Backend 2│   │ Backend 3│
        │  (NestJS)│   │  (NestJS)│   │  (NestJS)│
        └────┬─────┘   └────┬─────┘   └────┬─────┘
             │              │              │
             └──────────────┼──────────────┘
                            │
         ┌──────────────────┼──────────────────┐
         ▼                  ▼                  ▼
   ┌──────────┐      ┌──────────┐       ┌──────────┐
   │PostgreSQL│      │   Redis  │       │   EMQX   │
   │  + TSDB  │      │           │       │  (MQTT)  │
   └──────────┘      └──────────┘       └──────────┘

4. Security Architecture

Layer Implementation
Transport HTTPS/TLS
Auth JWT + refresh tokens
RBAC Permission-based with scope levels (none/assigned/own/all/system)
API Rate limiting, input validation
Database Parameterized queries, connection pooling
File Storage MinIO with presigned URLs

4.1 RBAC Implementation

Core Components:

  • AuthorizationPolicyService - Permission checking and scope resolution
  • ResourceScopeMap - Per-resource scope configuration
  • PermissionsGuard - OR-based permission checking

Permission Format: resource:action:scope (e.g., pond:read:all, device:update:own)

EffectiveScope Levels:

Scope Description
none No access
assigned Only resources assigned to user
own Resources created by user
all All resources in organization
system Cross-organization access (superadmin)

Resource Assignment Modes:

  • direct - Resources assigned directly to user (inventory, warehouse, supplier, pond)
  • by-pond - Resources accessible through assigned ponds (area, cycle, device, daily-log, growth-record)
  • none - Organization/role level (no resource assignment tracking)

Last updated: March 2026