What SAPI is, how its subsystems fit together, and the safety posture that shapes those boundaries. This is the workspace's own architecture overview — each subsystem's own docs (linked throughout) are the source of truth for its internals; this document exists to describe the concept that holds them together and should not drift into re-describing what a subsystem's own README/ADRs already say better.

1. What SAPI is

A collection of independently-versioned projects that together let you build, simulate, and test a redundant ERTMS Radio Block Centre (RBC): a 2oo2 (two-out-of-two) voting pair of vital channels, a non-vital gateway concentrating external traffic, the safety-oriented OS abstraction layer underneath all of it, and a full simulated environment (train, interlocking, CTC) to exercise the whole system without real trackside hardware. The core C/C++ code targets CENELEC EN 50128 / SIL 4 rigor (MISRA C:2012); the Python simulation and test tooling does not — it exists to exercise the SIL4 code, not to carry that rating itself.

2. Dependency graph

                    safeAPIFreamwork  (C99 OS abstraction: timers, IPC, memory, NVM,
                         │              channels/voting, safe-state transitions)
                         │
         ┌───────────────┼────────────────────────┐
         │               │                        │
safeAPIBackendPosix   safeCommFreamwork      (future: other OAL backends —
(POSIX/Linux OAL)      (ERTMS safe comms,      QNX, FreeRTOS, per the
         │              Subset-037/098,         toolchain projects below)
         │              skeleton stage)
         │                    │
         └──────────┬─────────┘
                    │
           safeAPIRBC2oo2GP  ──consumes──▶  safeAPIRBC2oo2GA  (shared lib, IL/CTC logic)
        (the reference RBC app:              safeAPIRBC2oo2SA  (site-data + installer packaging)
         A/B/C/SITE × WEST/EAST)
                    │
                    │  wire protocol (rbc_wire, hand-mirrored)
                    ▼
                 SimCore  (shared Python transport plumbing)
                    │
      ┌─────────────┼─────────────┐
      ▼             ▼             ▼
TrainRBCSim    ILRBCSim      CTCRBCSim
      │             │             │
      └─────────────┴─────────────┘
                    │
         safeAPIRBC2oo2TestEnv
   (Robot Framework + Docker Compose,
    drives the whole stack end to end)
 
CommServer — sits between TrainRBCSim and safeAPIRBC2oo2GP's role-C gateways,
             stubbing the real ISDN/FRMCS train-facing access point as plain TCP.
 
SAPIMacOSToolchain / LinuxMacOSToolchain / QNXMacOSToolchain / FreeRTOSToolchain —
             cross-compilation infrastructure, consumed by CMake's
             -DCMAKE_TOOLCHAIN_FILE=, not linked by anything above.

Dependency direction is one-way and never reverses: safeAPIRBC2oo2GP depends on safeAPIFreamwork/safeAPIBackendPosix/safeAPIRBC2oo2GA/safeAPIRBC2oo2SA; the three sims depend on SimCore; nothing upstream ever depends on something downstream. A change in a depended-on project that breaks a consumer is the consumer's problem to absorb, not the other way round. The one deliberate exception is safeCommFreamwork's stated design: nothing in it depends on safeAPIRBC2oo2* — a future revision of safeAPIRBC2oo2GP's transport code would consume it, not vice versa.

3. Two consumption paths, everywhere

Every C project installs to its own dist/<platform>/; every Python project builds a wheel into its own dist/. A downstream project consumes either via the plain mechanism (find_package() for C, pip install --find-links for Python — zero extra tooling) or via Conan (conan create . / requires = "...", one shared cache and real version resolution across the whole workspace). Both paths are kept working simultaneously; a Conan-only feature is a regression against the plain path and vice versa. See each subsystem's own CLAUDE.md "dist/ convention" section for its exact install layout.

4. Safety posture: vital, non-vital, and tooling

Tier	Subsystems	Posture
Vital, SIL 4	safeAPIFreamwork, safeAPIRBC2oo2GP/GA/SA (the A/B channel code paths), safeCommFreamwork's safecomm::safety/safecomm::cfm	MISRA C:2012, EN 50128 lifecycle discipline, no dynamic memory, full Doxygen traceability to docs/requirements/SRS.md per project.
Non-vital, safety-adjacent	safeAPIRBC2oo2GP's role-C Gateway paths, safeCommFreamwork's safecomm::ale/safecomm::config, CommServer	C99, careful but not SIL-rated — a fault here can drop or misroute a connection, never forge a vital decision, because the vital side independently verifies everything it receives (e.g. the EuroRadio MAC — see safeCommFreamwork/docs/architecture/ADR-002-stack-and-deployment.md §3).
Tooling, not safety-rated	SimCore, TrainRBCSim, ILRBCSim, CTCRBCSim, safeAPIRBC2oo2TestEnv, the four toolchain projects	Test/simulation/build infrastructure. Do not apply MISRA/EN 50128 rules here — each states its own (much lighter) conventions.

This split is why CommServer and the Gateway ALE (safecomm::ale) can be developed and iterated on quickly while the vital core stays under heavier process: they carry bytes they cannot authenticate or alter undetectably, so a bug in them degrades to a safe supervision-timeout, never a false permissive signal.

5. Where safe communication sits

safeCommFreamwork is the newest addition to the vital stack: it implements the ERTMS/ETCS Subset-037 (EuroRadio, EVC↔RBC) and Subset-098 (RBC↔RBC) safe-communication layers as a library safeAPIRBC2oo2GP will eventually link, replacing today's unauthenticated plain TCP. CommServer is the non-vital access point in front of it — today a plain-TCP stub standing in for the real ISDN/FRMCS train-facing bearer. See safeCommFreamwork/docs/architecture/ADR-002-stack-and-deployment.md for the full stack diagram and ADR-003-protocol-detail-and-build-out.md for the wire-level design and phased build-out plan; both projects are pre-integration today (safeCommFreamwork is a skeleton, CommServer speaks plain TCP with no SFM authentication yet).

6. Documentation map

Every subsystem is documented in Doxygen and published under this repository's single GitHub Pages site, https://bula173.github.io/SAPI/:

/ — this master spec (rendered from the root Doxyfile/README.md).
/<project-name>/ — one subpage per subsystem, generated from that project's own Doxyfile against its own README.md, headers/source, and docs/.

See each subsystem's own README (linked from the root README.md) for its build/test/run instructions — this document does not duplicate them.

7. What to read next

Building anything: REQUIREMENTS.md.
Agent/AI working notes, build history, cross-cutting gotchas: CLAUDE.md.
A specific subsystem: its own README, then its own CLAUDE.md/docs/ for depth.