System Design

This chapter provides a high-level overview of the Cocktail Machine. It defines the system boundaries, illustrates the core functional blocks, and documents the fundamental architectural decisions that shaped the design before diving into specific hardware or software implementations.

System Context

The system context describes the Cocktail Machine as a "black box" and identifies all external actors and systems that interact with it.

system-context

  • User (Guest): Interacts with the system purely to order and receive drinks. Requires zero technical knowledge.

  • Operator (Staff): Responsible for refilling ingredients, executing cleaning cycles, and calibrating pods. Interacts with a dedicated admin UI.

  • Power & Ingredients: The physical inputs required for operation.

Conceptual Building Blocks

Zooming into the machine, the system is partitioned into three functional domains.

conceptual-blocks

  • Station: Handles all high-level logic and user interactions. Both the Guest UI and the Operator Maintenance UI are hosted here.

  • Pod(s): Handle the low-level, real-time hardware execution. A Pod receives a command, executes it autonomously by driving its actuators, and reports back. Operators interact physically with Pods for maintenance.

  • Power Management Unit: The internal bridge between the external power grid and the low-voltage electronics.

The split of the Station and Pod’s is decided in ADR-001: Decentralized Hardware Architecture (Station + Pods)

Key Technology Decisions

The following technology choices are established at the system level and are assumed as given in the Station, Pod, and Protocol software architecture documents that build on this chapter. Only the decision itself is stated here. The rationale and alternatives considered are documented in the referenced ADR.

  • Physical Transport: Station and Pods communicate over USB, using the USB CDC device class — decided in ADR-002.

  • Pod Embedded OS: Pods run on Zephyr RTOS with C++ application support enabled — decided in ADR-005.

  • Protocol Codegen: The Station–Pod protocol schema and its generated C++ code are produced using commsdsl (CommsChampion Tools) — decided in ADR-006.

These three decisions are interdependent: the protocol code generated via commsdsl (ADR-006) targets plain, freestanding C++, which is what makes it usable unmodified on both the Station and on Zephyr-based Pods (ADR-005), over the USB CDC transport established in ADR-002. The Station, Pod, and Protocol software architecture documents build directly on this combination rather than re-deriving it.

Cross-Cutting Concepts

Some concerns affect both the Station and every Pod and are therefore defined once, here, rather than repeated in the Station or Pod software architecture documents.

Station–Pod Communication Protocol

The Station and every Pod communicate through a request–response protocol. The Station is the sole initiator of communication. A Pod never sends unsolicited commands. Every Pod is addressed by a unique identifier assigned at connection time, allowing the Station to route commands to a specific Pod and to attribute status and events back to their origin. This request–response model, including the Station’s role as sole initiator, is decided in ADR-003.

The protocol distinguishes three conceptual message categories:

  • Commands — issued by the Station to trigger an action on a Pod, e.g. dispense a given volume.

  • Status queries — issued by the Station to poll a Pod’s current state, e.g. connected, idle, dispensing, fault.

  • Events — emitted by a Pod in response to a command or an internal condition, e.g. dispensing completed, calibration done, error raised.

This document defines the protocol’s role and message categories at a conceptual level. The exact wire format, framing, and versioning strategy are defined in Protocol

Physical Transport

The Station and Pods are physically connected via USB, using the USB CDC class to carry the protocol described above. This choice keeps each Pod a self-contained, hot-pluggable unit that can be connected, removed, or replaced without rewiring the Station.

The detailed rationale, trade-offs, and alternatives considered (CAN, Ethernet) behind this interface choice are out of scope for this document and are captured separately in ADR-002, since the Station/Pod split (ADR-001) was decided independently of the transport used to realize it.

Power Architecture

All electrical energy for the machine originates from a single external 230V AC mains connection and is distributed internally as follows:

power-architecture

The main switch provides a single, clearly labeled point at which an operator can fully disconnect the machine from mains power. The RCD/circuit breaker protects against both residual current faults and overcurrent conditions before any DC conversion takes place. A continuous protective earth (PE) conductor is maintained across all stages, from the inlet through to the Station and every Pod. The detailed rationale for this power architecture is documented in ADR-004.

Safety Concept

The power and protocol design directly support the Human Safety and Food Safety quality goals:

Measure Supports

Main switch as a single manual disconnect point

Human Safety

RCD/circuit breaker on the AC input stage

Human Safety

Continuous PE conductor across all stages

Human Safety

Food-safe materials on all user-contact parts and flow paths

Food Safety

Domain Terminology

Station, Pod, and their related terms follow a single, canonical naming convention used consistently across hardware documentation, protocol definitions, and both software architecture documents. This convention is not repeated here — see Naming Conventions.