Hive Pal

Hive‑Pal is a self‑hosted, full‑stack application for managing beekeeping operations. From a developer standpoint it is built as two tightly coupled services—a NestJS‑powered REST API and a Vite/React single‑page frontend. The stack is intentionally lightweight yet modern: TypeScript on both sides, PostgreSQL as the relational store, and Docker Compose for reproducible deployments. The codebase is structured into clear domain modules (apiaries, hives, inspections, queens) which expose CRUD endpoints and a GraphQL‑style query language via OpenAPI docs. This modularity makes it straightforward to extend or replace individual parts without touching the core.

Architecture

• Backend – NestJS (Node.js 18+), TypeScript, @nestjs/typeorm for ORM, class-validator for DTO validation. The API follows a layered architecture: controllers → services → repositories. Security is handled by JWT authentication (Passport strategy) and role‑based access control. The database schema is defined in TypeORM entities, allowing migrations via typeorm migration:run.
• Frontend – Vite + React (TypeScript), react-query for data fetching, and Vite’s environment variables (VITE_API_URL) to point at the backend. The UI is mobile‑first, using responsive CSS and a component library (e.g., Radix or Tailwind) for rapid development.
• Database – PostgreSQL 15+, accessed through TypeORM. The schema is fully relational with foreign keys for apiary → hive, hive → inspection, etc.
• Containerization – A production‑ready docker-compose.prod.yaml bundles three containers: frontend, backend, and postgres. Each container exposes internal ports only; external access is via an override file or a reverse proxy.

Core Capabilities

• REST API – CRUD endpoints for all domain entities, with pagination, filtering, and sorting. The API is documented automatically by Swagger (/api-docs), providing interactive testing.
• Webhooks & Events – The backend emits events (e.g., hive.updated, inspection.created) that can be consumed by external services via a simple HTTP POST webhook configuration. This allows real‑time integrations with calendars, alerting systems, or custom dashboards.
• Plugin‑like Extensibility – While the current repo does not ship a formal plugin system, the modular service architecture means developers can fork or import modules. Adding a new domain (e.g., “Pesticide Tracking”) only requires creating a new TypeORM entity, service, controller, and updating the Swagger docs.
• Authentication & Authorization – JWT based auth with configurable expiration. Role definitions (ADMIN, USER) are stored in the database and can be extended via a roles table.

Deployment & Infrastructure

• Self‑Hosting – Docker Compose is the recommended deployment method. All services are containerized; no additional runtime is required beyond Docker and a PostgreSQL instance (which can be swapped for other RDBMS with minimal changes).
• Scalability – The stateless backend can be scaled horizontally by adding more backend replicas behind a load balancer. The PostgreSQL database can be promoted to read‑replicas or moved to a managed cluster for higher throughput.
• Environment Configuration – All secrets and URLs are injected via environment variables (.env). The backend exposes a health check endpoint (/health) for orchestrators, and the frontend can be served behind any reverse proxy (NGINX, Caddy, Traefik).
• CI/CD – The repository includes GitHub Actions that run tests and build Docker images, ensuring a reproducible pipeline for developers.

Integration & Extensibility

• API Clients – The OpenAPI spec can be used to generate client libraries in any language (TypeScript, Python, Go). This is useful for building custom mobile apps or command‑line tools.
• Webhooks – External services can register URLs to receive event payloads. The payload structure is JSON‑serializable and documented in the Swagger UI.
• Custom Frontend – Since the frontend is a SPA, developers can replace it with any framework (Vue, Svelte) by consuming the same API. The VITE_API_URL variable keeps the integration simple.
• Database Migrations – TypeORM migrations are versioned and can be applied manually or via CI, allowing smooth schema evolution.

Developer Experience

• Documentation – The repo contains a comprehensive README, API docs (/api-docs), and inline comments. TypeScript types provide strong typing for both client and server code.
• Community & Support – Although still a WIP, the project follows semantic versioning and uses GitHub Issues for feature requests. The CI pipeline ensures that breaking changes are flagged early.
• Configuration Flexibility – Nearly every runtime setting is exposed as an environment variable, making it trivial to switch between development and production or to integrate with external services (SMTP, reverse proxies).

Use Cases