autonomy-logic/openplc-runtime

1. This repository is a headless PLC runtime, not a user-facing app. Its architecture is centered on two cooperating processes: a Python web server that exposes the control plane, and a C/C++ PLC runtime that executes IEC 61131-3 logic with real-time scheduling.

2. The top-level boundary is between the external controller and the runtime. The main external client is the OpenPLC Editor v4, which uploads programs, polls compilation state, starts/stops execution, and connects to debug streams. There is also support for cloud-controlled operation via Autonomy Edge Cloud, but the same runtime-facing APIs are used.

3. The Python subsystem in webserver/ is the orchestration layer. It hosts the HTTPS REST API, JWT authentication, user management, file upload validation, runtime status endpoints, and the Socket.IO/WebSocket debug interface. It also manages startup/shutdown of the PLC runtime process and bridges editor requests into runtime commands.

4. The C/C++ subsystem in core/src/plc_app/ is the execution engine. It owns PLC state, scan-cycle timing, watchdog/logging utilities, socket communication, and dynamic loading of compiled PLC programs. This is the part that must stay deterministic and is the only layer that needs real-time priority.

5. Communication between the two main processes happens over Unix domain sockets under /run/runtime/. That IPC boundary is important: the web server does not execute PLC code directly; it sends control commands and receives logs/status through the socket while the runtime remains isolated as a separate process.

6. Program deployment follows a compile-and-load pipeline. The editor uploads a ZIP package to the web server, the server validates and extracts it, and the build flow compiles it into a shared library. The runtime then loads that shared library dynamically, so PLC logic is treated as a deployable binary artifact rather than source code executed in place.

7. The scan-cycle and I/O boundary lives inside the runtime plus the driver layer. core/src/drivers/ provides the plugin system for hardware interaction, with plugin configuration, driver abstractions, and plugin-specific implementations. This is where external fieldbus or device communication is integrated into the PLC loop.

8. The driver subsystem is split by implementation language. Native plugins include EtherCAT and S7comm, while Python plugins cover Modbus master/slave and OPC UA. Shared Python support code in core/src/drivers/plugins/python/shared/ provides buffer access, config decoding, type conversion, synchronization, and logging so plugins can interact with PLC memory safely and consistently.

9. OPC UA is a significant protocol-specific subsystem within the Python plugins. It has its own address-space, security, subscription, and server modules, plus dedicated tests and config models. In architectural terms, it acts as both a network-facing data server and a bridge into PLC memory/debug data.

10. The runtime has a security and control plane layered on top of the transport. TLS is used on port 8443, authentication is JWT-based, upload handling includes validation against path traversal and archive abuse, and secrets are stored in the runtime data directory. These controls live mainly in the Python web layer, not in the real-time core.

11. Build and packaging are split across tooling layers. CMake builds the C/C++ runtime and native plugin code; Python packaging/venvs support the web server and Python plugins; Dockerfiles and GitHub workflows package cross-platform runtime images and installers. The build outputs include the PLC executable and compiled program libraries.

12. For an architecture diagram, the key nodes are: external editor/cloud client, Python web/API server, Unix-socket IPC, PLC runtime core, dynamic PLC program library, and plugin drivers reaching hardware/network protocols. The main data flow is editor upload -> validation/compile -> shared library load -> real-time scan cycle -> plugin I/O and debug/status back to the editor.