> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/development/architecture.md). # 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 #### Required Environment Variables All pyck services require the following environment variable: * **`PYCK_ENV`** (required): Environment identifier used for resource naming and namespace construction * Must be set explicitly in all deployment configurations * No default value — application will crash at startup if missing * Examples: `production`, `staging`, `dev`, `local` * Used to construct namespace names (e.g., `pyck-{PYCK_ENV}-workers`) **Breaking Change Notice**: As of commit `15ffdc33` (April 2026), the previous default value of "local" has been removed. All deployments must now explicitly set `PYCK_ENV` in their environment configuration or ConfigMap. ### 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 #### Worker Health Monitoring Each Temporal worker automatically exposes a `/health` HTTP endpoint (default port 8080) that verifies the worker is actively polling Temporal. The health check: * Queries Temporal to confirm this worker's identity appears in the task queue poller list * Returns **200 OK** when the worker is healthy and polling * Returns **503 Service Unavailable** when the worker has stopped polling or cannot reach Temporal Configuration (all optional): * **`HEALTH_DISABLED`**: Set to `1` to disable health checks * **`HEALTH_PORT`**: HTTP port (default: `8080`) * **`HEALTH_INTERVAL`**: Probe frequency (default: `10s`) * **`HEALTH_TIMEOUT`**: RPC timeout per probe (default: `3s`) * **`HEALTH_MAX_STALE`**: Maximum age of last success before marking unhealthy (default: `90s`) This health endpoint integrates with Kubernetes liveness probes and fly.io health checks to automatically restart workers that have silently stopped processing workflows. This architecture ensures that each tenant's workflow executions run in isolated workers while maintaining efficient resource utilization across the system. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.pyck.cloud/development/architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.