Architecture

System Architecture

Audience: Programmer

System Architecture

pyck is a modular microservices platform built in Go that provides a comprehensive logistics solution for warehousing operations. The architecture follows modern microservices principles with clear separation of concerns.

Core Components

1. Gateway Service

   • Aggregates GraphQL schemas from all services

   • Provides a unified API endpoint

   • Handles authentication and request routing

2. Domain Services

   • Main Data Service: Core data operations and primary data entities

   • Inventory Service: Stock levels, item movements, and inventory management

   • Management Service: System configurations and company-related information

   • Picking Service: Order picking workflow and processing

   • Receiving Service: Inbound shipment processing

   • File Service: File storage and document management

   • Workflow Service: Background task execution and process automation

Technical Infrastructure

pyck leverages several key technologies:

• GraphQL: Main API interface with federation across services

• PostgreSQL: Primary data storage

• NATS.io: Event streaming and service messaging

• Temporal.io: Workflow orchestration and reliable task execution

• Docker: Containerization for consistent deployment

• Zitadel: Authentication and authorization

• MinIO/S3: Object storage for files and attachments

Service Communication

Services communicate through:

1. GraphQL Federation: For data queries and mutations

2. Event Streaming: Using NATS for asynchronous events

3. Workflow Orchestration: Temporal for complex process flows

Development Approach

The codebase follows these principles:

• Go Backend: All backend services are written in Go

• Infrastructure as Code: Docker Compose and Taskfile for automated setup

• API-First Design: GraphQL schema definitions drive implementation

• Code Generation: Models and GraphQL adapters are generated using entgo

• CRUD+ System: Backend provides common basic functions for all warehouses

• Process Workflows: Complex business logic implemented via temporal processes

Deployment Model

pyck can be deployed as:

• Local Development Environment: Using Docker Compose

• Kubernetes Cluster: Using Helm charts for production deployment

Tenant Worker Architecture

pyck implements a per-tenant worker deployment model for Temporal workflows:

• Automatic Provisioning: During tenant registration, the system automatically deploys a dedicated Temporal worker for each tenant

• Kubernetes Integration: Workers are deployed as Kubernetes custom resources using the temporal-worker-controller

• Isolation: Each tenant gets its own worker deployment, ensuring workload isolation and independent scaling

• Resource Management: Worker deployments are created in a shared workers namespace with configurable resource limits (CPU: 100m-500m, Memory: 256Mi-512Mi)

Worker Deployment Components

When a new tenant is registered, the following Kubernetes resources are created:

1. Workers Namespace: A shared namespace for all tenant workers (e.g., {environment}-workers)

2. TemporalConnection CRD: Defines the connection to the Temporal service (shared per environment)

3. TemporalWorkerDeployment CRD: Creates a dedicated worker deployment for the tenant

Worker Deployment Configuration

Worker deployments can be configured via environment variables:

• PYCK_FLAVOUR_GO_WORKER_REPLICAS: Number of worker pod replicas per tenant (default: 2)

  • Controls horizontal scaling of tenant worker deployments

  • Higher values provide better availability and throughput

  • Should be tuned based on expected workflow load per tenant

This architecture ensures that each tenant's workflow executions run in isolated workers while maintaining efficient resource utilization across the system.