SAPI is a workspace of independent, separately-versioned C/C++ and Python projects for building safety-related railway software around an ERTMS Radio Block Centre (RBC), targeting CENELEC EN 50128 / SIL 4. Each subproject is its own git repository with its own history, README, and (where applicable) Doxygen documentation; this root ties them together as a reproducible whole.

For the full picture — what each subsystem does, how they depend on each other, and the safety posture split between vital and non-vital code — see docs/architecture/MASTER_SPEC.md. For AI-agent-oriented working notes (build history, known issues, session-by-session detail) see CLAUDE.md.

Getting the code

Two ways to check this workspace out, both valid:

A single subproject on its own — e.g. git clone git@github.com:bula173/safeAPIFreamwork.git — works exactly as if this root repo didn't exist.
The whole workspace, pinned to reproducible commits — git clone --recurse-submodules git@github.com:bula173/SAPI.git checks out this root repo plus every subproject below at the exact commit this root currently pins (via .gitmodules). Already have a plain clone? git submodule update --init --recursive does the same from there.

Either way, once the tree is on disk: see REQUIREMENTS.md for what needs to be installed (compiler, CMake, Python, optional cross-compilation toolchains, static-analysis/docs tooling), then ./installDependencies.sh (installs the required tools on a bare macOS or Ubuntu/Fedora machine) and ./bootstrapWorkspace.sh (clones every subproject at its current branch tip — not pinned, unlike the --recurse-submodules path above; useful for active development across repos).

Subsystems

Project	What it is
safeAPIFreamwork	The core C99 safety-oriented OS abstraction library (timers, IPC, memory, redundancy/voting, safe-state transitions) every other C project builds on.
safeAPIBackendPosix	The POSIX/Linux OAL backend for safeAPIFreamwork.
safeCommFreamwork	ERTMS/ETCS safe communication (Subset-037 EuroRadio, Subset-098 RBC/RBC) — currently a skeleton, see its own ADR-003 for the build-out plan.
safeAPIRBC2oo2GP	The reference application: a multi-process 2oo2 redundant RBC pair (roles A/B/C/SITE × WEST/EAST) built on the framework.
safeAPIRBC2oo2GA	Generic Application — IL/CTC route logic, linked into GP as a shared library.
safeAPIRBC2oo2SA	Specific Application — installer packaging + site-data libraries for GP/GA.
CommServer	Non-vital customer-network access point — the stub train-facing TCP relay in front of the RBC's role-C gateways.
SimCore	Shared Python transport-layer plumbing (wire codec, dual-homed link, control-port server) for the three sims below.
TrainRBCSim	Train (EVC) simulator driving the RBC over its wire protocol.
ILRBCSim	Interlocking simulator — grants/extends Movement Authority.
CTCRBCSim	CTC simulator — observes train-connected / MA-granted indications.
safeAPIRBC2oo2TestEnv	End-to-end Robot Framework test suite + Docker Compose stack for the whole system.
SAPIMacOSToolchain	Native macOS (Xcode/Homebrew) toolchain pin.
LinuxMacOSToolchain	Cross-compiling to Linux ARM/x86 from macOS.
QNXMacOSToolchain	QNX cross-compilation scaffold (needs a licensed SDP).
FreeRTOSToolchain	Bare-metal ARM (Cortex-M) toolchain + vendored FreeRTOS kernel.

All except safeCommFreamwork and CommServer are registered as git submodules of this repo (.gitmodules); those two are newer and local-only so far — see the root CLAUDE.md for why, and add them the same way once they get a GitHub remote.

Documentation site

Every subsystem above is documented with Doxygen; this root publishes all of it as one GitHub Pages site at https://bula173.github.io/SAPI/, with each subsystem under its own path (https://bula173.github.io/SAPI/<project-name>/). See docs/architecture/MASTER_SPEC.md for the map.