# 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](./data-models-main.md).

## 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](./api-contracts-main.md).

## 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](./source-tree-analysis.md).

## 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](./development-guide-main.md).

## 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.
