Architecture Document - Main

1. Executive Summary

The Pig Farm Controller is a backend application developed in Go, utilizing the Echo web framework and GORM ORM. It provides a comprehensive set of APIs for managing various aspects of a pig farm, including user management, device control, plan execution, pig batch management, and data monitoring. The application is designed as a layered, API-centric backend service.

2. Technology Stack

Category	Technology	Version
Language	Go	1.25
Web Framework	Echo	v4.13.4
ORM	GORM	v1.30.5
Database Driver	PostgreSQL
Database Driver	SQLite
Logging	Zap	v1.27.0
Documentation	Swaggo	v1.16.6
JWT	golang-jwt/jwt	v5.3.0
UUID	google/uuid	v1.6.0
Concurrency	Ants	v2.11.3
Scheduling	Cron	v3.0.1
Testing	Testify	v1.11.1
Serial Port	tarm/serial
Cryptography	golang.org/x/crypto	v0.43.0
Protobuf	google/protobuf	v1.36.9
YAML	gopkg.in/yaml.v2	v2.4.0

3. Architecture Pattern

The application follows a layered/API-centric backend service architecture. It exposes a RESTful API to interact with various functionalities. The core logic is organized into application, domain, and infrastructure layers, promoting separation of concerns and maintainability.

4. Data Architecture

The application utilizes a PostgreSQL database, with support for TimescaleDB for time-series data. GORM is used as the Object-Relational Mapper. The database schema consists of 33 tables, covering entities such as Users, Devices, Plans, Pig Batches, Farm Assets (Pig Houses, Pens), Sensor Data, Medications, and Notifications. Key tables include:

User
Device
Plan
PigBatch
PigHouse
Pen
SensorData
Medication
Notification

For a complete list of data models, refer to Data Models - Main.

5. API Design

The API is designed as a RESTful interface, primarily using JSON for request and response bodies. It includes both public and authenticated endpoints. Authentication is handled via JWT. The API covers a wide range of functionalities, including:

User authentication and management.
CRUD operations for devices, device templates, area controllers, plans, pig houses, and pens.
Comprehensive pig batch management, including transfers, sales, purchases, and health records.
Monitoring endpoints for various logs and sensor data.

For a detailed list of API endpoints, refer to API Contracts - Main.

6. Component Overview

The application is structured into several key components:

Application Layer (internal/app): Handles API routing, controllers, DTOs, middleware, and application-specific services.
Core Layer (internal/core): Contains core application setup and initialization logic.
Domain Layer (internal/domain): Encapsulates the business logic and domain entities for various modules like audit, device, pig, scheduler, etc.
Infrastructure Layer (internal/infra): Manages external concerns such as database interactions, logging, configuration, and external communication (e.g., LoRaWAN ChirpStack integration).

7. Source Tree

For a detailed breakdown of the project's directory structure and the purpose of each critical folder, refer to Source Tree Analysis - Main.

8. Development Workflow

The development workflow involves standard Go practices, including dependency management with go mod, building with go build (or make), and testing with go test. Configuration is externalized via config.yml.

For detailed development instructions, refer to Development Guide - Main.

9. Deployment Architecture

While no explicit Dockerfiles or CI/CD configurations were found, the application is a self-contained Go binary. Deployment typically involves compiling the application, configuring the config.yml for the target environment, and running the executable. It is designed to interact with an external PostgreSQL database and ChirpStack LoRaWAN server.

10. Testing Strategy

Testing is primarily conducted using Go's built-in testing framework, with github.com/stretchr/testify for assertions. Tests are typically located alongside the code they test, following Go conventions.

4.6 KiB Raw Blame History