architecture

The tin architecture is organized around small C++ dependency surfaces. Each surface names a specific role in a deterministic system: runtime mechanics and actor composition, behavior modeling, portable I/O contracts, platform contracts, and application adapters.

New contributors should start with developer_onboarding.md, which gives a reading path, repository map, change workflow, and review checklist for this architecture.

The dependency direction is intentionally simple:

application or domain layer
        |
        v
tsm behavior model       tio I/O contracts
        |                      |
        v                      v
runtime primitives       thal platform contracts
        \                      /
         v                    v
              tin facade

Application code can depend on the narrowest surface it needs. A state-machine library can depend on tsm; a driver adapter can depend on tio and thal; a system shell can depend on tin when it intentionally uses the combined framework facade.

Public Surfaces

• tin is the combined API for runtime, state-machine, I/O, and platform contracts.
• channels covers fixed-capacity typed storage and overflow policy.
• actors covers typed ports, actor links, actor groups, and caller-owned local execution.
• coroutines covers static coroutine tasks, awaitables, executor-driven wakeups, tick sleeps, cancellation, and task resources.
• runtime is the lower-level reference surface: tasks, timers, sync primitives, resource accounting, local typed event delivery, and formal contracts.
• tsm is the state-machine surface: HSM authoring, transitions, hierarchy, orthogonal regions, synchronization, history, and deferred events.
• tio is the portable I/O facade layer: small payload types and concepts for GPIO, ADC, UART, SPI, I2C, CAN, PWM, and async-shaped driver facades.
• thal is the platform/HAL boundary: target profiles and target adapter contracts.

Boundary Rule

tin APIs define deterministic contracts and bounded handoff records. Application, domain, and target adapter layers use those primitives for product-specific policies.

Facade Headers

Use facade headers to name the dependency boundary directly:

#include "tin/runtime.h"
#include "tin/tsm.h"
#include "tin/io.h"
#include "tin/platform.h"
 
tin::channel<int, 4> samples;
static_assert(tin::io::gpio_input<MyButton>);

The tin headers provide the common API used by examples, tests, and target adapters.