Architecture

Architecture

Theia is Functional Clusters on a C++ actor runtime, supervised by a fork/exec orchestrator. This page covers the three layers: the runtime, the supervisor, and the FC catalog. For the conceptual AUTOSAR mapping see Manifest-Structure-and-ARA-Requirements; for how the .art model becomes running software see Deployment-Manifest-Generation-and-Serialization.

The Theia C++ runtime

platform/runtime/include/ is an OTP-faithful actor runtime. There is one thread per node. The .art node shape picks one of three base classes:

Base class	Shape	Callbacks
GenServer	sync-first mailbox actor	handle_call (request → reply), handle_cast (fire-and-forget), handle_info (unrouted TIPC frame / internal signal)
GenStateM	finite state machine (Erlang gen_statem shape)	per-state event handlers + timeouts
GenRunnable	free worker thread	do_start / do_loop / do_stop

handle_info's default is CRITICAL + abort — an unrouted frame means the netgraph drifted from the wire, which is treated as a bug.

Transport and codecs

• TIPC is the transport. TipcMux is the per-process listener; it carries nanopb wire bytes (not full libprotobuf — that is confined to the gRPC edge in com).
• RemoteRef / NodeRef do correlated request/reply over TIPC.
• RemoteCodec hashes a stable 16-bit service_id per message type, so the receiver can route a frame to the right handler.
• Tracer emits [header][proto-wire] records when a node is selectively enabled, feeding the log[trace] hub (see the catalog below).

Generated code (lib/, main/, BUILD) is never hand-edited; the app-owned, write-once files are impl/<Node>_handlers.cc (handler bodies) and impl/<Node>_state.hh (the node's state struct). To change generated output you change the .art and re-run gen-app.

The supervisor

platform/supervisor/ is a fork/exec orchestrator — one OS process per FC binary (and per vendor app) — that owns Function-Group state. It is Theia's realization of AUTOSAR Execution Management (there is no separate exec process).

• OTP-style lifecycle: forks and execs each child, supervises it, and reaps it; theia stop is a single batch SIGTERM reaped against one deadline.
• Control surface: exposed as a gen_server node on the standard Theia transport (nanopb ControlRequest). Operations include StartChild, RestartChild, TerminateChild, DeleteChild, ConfigureTrace, and ConfigureLogLevel.
• Heartbeat watchdog: each reporting node beats the supervisor; a missed beat marks the child degraded / for restart.

External tools never speak TIPC to the supervisor directly. The com FC bridges Theia ↔ gRPC, so operator tools (rtdb, the supervisor GUI, rf-theia) reach the control surface over an IP connection on :7700. See Advanced-Tools.

The Functional Cluster catalog

The full set of 18 AUTOSAR FCs is enumerated in artheia/artheia/manifest/clusters.py (CLUSTERS / BY_SHORT). Six ship a real daemon today; the rest are placeholders that carry a TIPC slot and the AUTOSAR-named interface contract but run no process.

short	Functional Cluster	Role in Theia	Daemon?
com	Communication Management	the gRPC bridge (supervisor ↔ external tools); a two-codec proxy (nanopb on the Theia side, libprotobuf/gRPC on the wire)	✅
log	Log & Trace	logs go direct to the sink; log[trace] is a logcat-style ring-buffer trace hub that observers Subscribe to over TIPC	✅
per	Persistency	the config gatekeeper & sole etcd client (etcd at 127.0.0.1:2379); stores per-node config <Msg> as digest-versioned proto bytes (NOT params — see Configuration-and-Migration)	✅
sm	State Management	a GenStateM FSM	✅
ucm	Update & Config Management	software update / config record	✅
shwa	Safe Hardware Accelerator	pinned to the compute machine	✅
exec	Execution Management	realized BY the supervisor, not a separate process	⛔ (nop)
core, crypto, diag, fw, idsm, nm, osi, phm, rds, tsync, vucm	(various)	AUTOSAR placeholders	⛔ (nop)

Each real FC lives at services/<fc>/system/<fc>/{package,component}.art (the spec) plus services/<fc>/{lib,main,impl}/ (generated + hand-owned C++). The daemons build independently of any rig, e.g.:

bazel build --config=linux //services/com/main:com //services/sm/main:sm \
  //services/log/main:log //services/per/main:per //services/ucm/main:ucm \
  //services/shwa/main:shwa