Development

Local Setup

Make sure the following tools are installed on your machine:

Node.js (LTS recommended)
Docker and Docker Compose
Git

No global installation of databases, MQTT brokers, or Zigbee tooling is required outside Docker.

Installing locally (for development)

To install Sparrow Home locally, first clone the repository:

git clone https://github.com/sparrow-codes/sparrow-home.git

Then install the dependencies:

cd sparrow-home npm install

warning

This configuration is for local development only. Do not use it in production.

A configuration file is required to run Sparrow Home locally in development mode:

.env for the backend (NestJS)

It is environment-specific and will not be added to version control. You can use the provided example files as a starting point.

Backend Configuration

Backend configuration is read from:

apps/server/.env

example file:

mode='development' dbHost=localhost dbPort=5432 dbUserName=sparrow dbPassword=sparrow dbName=sparrow_home
                    jwtSecret=REPLACE_WITH_RANDOM_STRING jwtExpiry=5d mqttUrl=mqtt://localhost:1883

Start the application locally

For convenience, a docker-compose.yaml file is provided to start the application locally.

docker compose -f ./docker-local/docker-compose.yaml -p docker up -d

Run frontend:

npx nx run sparrow-home-mobile:serve:development

Run backend:

npx nx run server:serve:development

success

You now have a fully functional Sparrow Home installation running locally. Go to http://localhost:4200 to see the application.

API Interfaces

This page provides an overview of the API interfaces available in Sparrow Home REST endpoints.

Auto-generated services

Sparrow Home uses NestJS Swagger module to auto-generate API documentation and client services. The API documentation is available at:

http://localhost:3000/api

once the server is running.

This approach allows you to easily integrate Sparrow Home with your existing applications. The generated services can be used to interact with the backend API without needing to manually write HTTP requests.

info

To include classes and methods you need to add Swagger decorators to the class and method definitions. For example:

import { Body, Controller, Get, Put, UseGuards } from '@nestjs/common'; import { ApiBearerAuth,
                        ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger'; import { AuthGuard } from
                        '@sparrow-server/auth'; import { AlarmService } from '../services/alarm.service'; import {
                        GetAlarmModeResponse } from './model/get-alarm-mode.response'; import { SetAlarmModeRequest } from
                        './model/set-alarm-mode.request'; @ApiTags('Alarm') @UseGuards(AuthGuard) @ApiBearerAuth()
                        @Controller('alarm') export class AlarmController { public constructor(private readonly _alarmService:
                        AlarmService) {} @ApiOperation({ operationId: 'setAlarmMode' }) @Put('set-mode') public async
                        setAlarmMode(@Body() request: SetAlarmModeRequest): Promise<void> { await
                        this._alarmService.setAlarmMode(request.isActive); } @ApiOperation({ operationId: 'getAlarmMode' })
                        @ApiResponse({ type: GetAlarmModeResponse }) @Get('mode') public async getAlarmMode():
                        Promise<GetAlarmModeResponse> { return this._alarmService.getAlarmMode(); } }

This is crucial to ensure that the generated services are correctly configured and ready to use. If your IDE does not provide auto-completion or type checking for the generated services, its probably because the decorators are not properly applied.

Architecture

Overall Architecture

The system is organized as a Nx monorepo, separating runtime applications from shared domain libraries. The apps directory contains the main executable applications, including the backend server (server) and the mobile application (sparrow-home-mobile).

The frontend layer is located under libs/fe and follows a domain-oriented structure, separated into domain and feature layers. The backend is built with NestJS and organized under libs/nest, where functionality is grouped into dedicated modules.

The architecture promotes clear separation of concerns: applications inside apps compose the final runtime environments, while business logic, integrations, and reusable features are encapsulated within shared libraries. This approach improves scalability, maintainability, code reuse, and independent development across frontend, mobile, and backend layers.

Frontend Technology Stack

The frontend is built with a modern technology stack centered around Angular as the primary framework for web and mobile application development.

State management is implemented using NgRx Signal Store, allowing reactive and lightweight state handling with Angular Signals integration. This approach simplifies data flow management, improves performance, and reduces boilerplate compared to traditional state management solutions.

Internationalization is handled with ngx-translate, providing dynamic multi-language support and flexible runtime translation loading across the application.

The UI layer is based on PrimeNG, which serves as the primary design system and component library for the project. PrimeNG provides a consistent visual language, reusable UI components, responsive layouts, and theming capabilities, significantly speeding up frontend development while maintaining a unified user experience across the application.

Combined with the Nx monorepo architecture, this stack enables modular development, code reuse between platforms, and efficient scaling of frontend functionality.

Backend Technology Stack

The backend is built with NestJS, providing a modular and scalable server-side architecture based on TypeScript. The application is organized into dedicated functional modules which improves separation of concerns and simplifies long-term maintenance and feature expansion.

Communication with the database is handled using PostgreSQL together with TypeORM, which is responsible for entity mapping, repository management, and database interaction. The project uses dedicated database migration scripts to manage schema evolution in a controlled and versioned way.

The REST API is fully documented using Swagger/OpenAPI generation integrated with NestJS. API documentation is automatically generated from application decorators and DTO definitions, ensuring that the documentation stays synchronized with the implementation. This significantly improves developer experience, simplifies frontend-backend integration, and provides a clear contract for external integrations and future extensions of the system.

Summary

Sparrow Home uses a modular, monorepo-based architecture designed for scalability and clear separation of concerns.

Monorepo foundation: Nx monorepo structure with runtime applications in apps and shared libraries in libs.
Frontend stack: Angular with NgRx Signal Store for reactive state management, ngx-translate for i18n, and PrimeNG as the main UI component library.
Backend stack: NestJS (TypeScript) organized into functional modules to support maintainability and feature growth.
Data layer: PostgreSQL with TypeORM for data access and entity mapping, supported by versioned database migrations.
API documentation: Swagger/OpenAPI generation integrated with NestJS to keep API docs aligned with implementation.

This combination enables code reuse across web, mobile, and backend layers while keeping development independent and maintainable.

Local Setup

Installing locally (for development)

Backend Configuration

Start the application locally

API Interfaces

Auto-generated services

Architecture

Overall Architecture

Frontend Technology Stack

Backend Technology Stack

Summary

Product

Resources

Community

Legal