Tech Stack

Complete reference of technologies powering AsaHome Cloud.

Backend Stack

Runtime & Framework

Technology	Version	Purpose
Node.js	20+	JavaScript runtime
NestJS	10.x	Progressive Node.js framework
TypeScript	5.x	Type-safe JavaScript

Why NestJS?

NestJS was chosen for its:

• Modular Architecture: Clean separation of concerns
• TypeScript First: Full type safety out of the box
• Dependency Injection: Testable, maintainable code
• Decorators: Express-like but with structure
• Built-in WebSocket Support: Socket.IO integration
• OpenAPI/Swagger: Automatic API documentation

Database

Technology	Version	Purpose
PostgreSQL	16	Primary relational database
TypeORM	0.3.x	Object-Relational Mapping

TypeORM features used:

// Entity example with TypeORM decorators
@Entity('devices')
export class Device {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ unique: true })
  uuid: string;

  @Column({ default: false })
  isOnline: boolean;

  @Column({ type: 'jsonb', nullable: true })
  metadata: Record<string, any>;

  @CreateDateColumn()
  createdAt: Date;
}

Authentication & Security

Technology	Purpose
Passport.js	Authentication middleware
@nestjs/jwt	JWT token generation/validation
bcrypt	Password hashing (12 rounds)
Helmet.js	Security headers
@nestjs/throttler	Rate limiting

JWT Configuration

JwtModule.register({
  secret: process.env.JWT_SECRET,
  signOptions: { 
    expiresIn: '15m',  // Access token
  },
})

Password Security

// bcrypt with 12 salt rounds
const hashedPassword = await bcrypt.hash(password, 12);

Real-time Communication

Technology	Version	Purpose
Socket.IO	4.x	WebSocket library
@nestjs/websockets	-	NestJS WebSocket integration

WebSocket Gateway

@WebSocketGateway({
  namespace: '/tunnel',
  cors: {
    origin: process.env.CORS_ORIGINS?.split(','),
    credentials: true,
  },
})
export class TunnelGateway {
  @WebSocketServer()
  server: Server;

  @SubscribeMessage('tunnel:message')
  handleMessage(@MessageBody() data: TunnelMessage) {
    // Route message to device
  }
}

Infrastructure

Containerization

Technology	Purpose
Docker	Container runtime
Docker Compose	Multi-container orchestration
Alpine Linux	Minimal base images

Dockerfile

# Multi-stage build for production
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/main.js"]

Reverse Proxy

Technology	Version	Purpose
Nginx	Alpine	Reverse proxy, TLS termination

API Documentation

Technology	Purpose
@nestjs/swagger	OpenAPI spec generation

OpenAPI Setup

The API uses NestJS Swagger module to generate OpenAPI specifications:

const config = new DocumentBuilder()
  .setTitle('AsaHome Cloud API')
  .setDescription('API for remote AsaHome OS access')
  .setVersion('1.0')
  .addBearerAuth()
  .build();

const document = SwaggerModule.createDocument(app, config);

Test the API using Postman or any HTTP client at https://cloud.asahome.io/api/v1

Development Tools

Testing

Tool	Purpose
Jest	Unit and integration testing
Supertest	HTTP assertion library
@nestjs/testing	NestJS testing utilities

Code Quality

Tool	Purpose
ESLint	Code linting
Prettier	Code formatting
Husky	Git hooks
lint-staged	Run linters on staged files

CI/CD

Tool	Purpose
GitHub Actions	CI/CD pipelines
Docker Hub	Container registry

Package Dependencies

Production Dependencies

{
  "@nestjs/common": "^10.0.0",
  "@nestjs/core": "^10.0.0",
  "@nestjs/jwt": "^10.0.0",
  "@nestjs/passport": "^10.0.0",
  "@nestjs/platform-express": "^10.0.0",
  "@nestjs/platform-socket.io": "^10.0.0",
  "@nestjs/swagger": "^7.0.0",
  "@nestjs/throttler": "^5.0.0",
  "@nestjs/typeorm": "^10.0.0",
  "@nestjs/websockets": "^10.0.0",
  "bcrypt": "^5.1.0",
  "class-transformer": "^0.5.1",
  "class-validator": "^0.14.0",
  "helmet": "^7.0.0",
  "passport": "^0.7.0",
  "passport-jwt": "^4.0.1",
  "passport-local": "^1.0.0",
  "pg": "^8.11.0",
  "socket.io": "^4.7.0",
  "typeorm": "^0.3.17"
}

Development Dependencies

{
  "@nestjs/cli": "^10.0.0",
  "@nestjs/testing": "^10.0.0",
  "@types/bcrypt": "^5.0.0",
  "@types/jest": "^29.5.0",
  "@types/node": "^20.0.0",
  "@types/passport-jwt": "^3.0.0",
  "eslint": "^8.0.0",
  "jest": "^29.5.0",
  "prettier": "^3.0.0",
  "supertest": "^6.3.0",
  "ts-jest": "^29.1.0",
  "typescript": "^5.0.0"
}

Version Requirements

Requirement	Minimum Version
Node.js	20.0.0
npm	9.0.0
Docker	24.0.0
Docker Compose	2.20.0
PostgreSQL	16.0

Next Steps

• Project Structure - Source code organization
• Development Guide - Local development setup