What this is.
Opinion + Experience + Fact (50% opinion · 30% experience · 15% fact · 5% fiction)
Written in collaboration with AI — I discuss, I do not outsource.

Chapter 1. The Space Above the RTOS

Every embedded codebase I have shipped over 20+ years lives in the same shape 🛠️.

At the bottom: hardware, drivers, the chip-vendor SDK. Above that: the RTOS — the scheduler, the primitives, the timing guarantees. Above the RTOS: the application — sensors read, motors turn, telemetry flows, fault recovery kicks in.

Between the RTOS and the application is a space. Most teams have lived with this space implicit.

That implicit space is where the team's actual decisions live. How modules talk. Who owns state. What happens on fault. How observability flows. Right now, in most embedded codebases, those decisions sit in the heads of two or three senior engineers and in the code itself — read-only access, in both directions.

The shift in 2026 is that this space has a name. Naming it on day one is the move that compounds.

▸ First principle. The space above the RTOS has always existed. Naming it is what lets the team and the AI agent build on the same foundation.

Chapter 2. What Actually Lives in the Layer

A working application architecture layer is short. Five elements 📋, each one a few pages, each one written once.

Module lifecycle. The states every module passes through — created, initialised, running, faulted, stopped — and who drives those transitions. Boot ordering follows from the lifecycle, instead of getting rediscovered every project.

Message contracts. What types of messages flow between modules. The schema for each. Which module owns publishing each, which module subscribes. Every cross-module exchange has a name and a type.

State-machine convention. How non-trivial behavior is structured. A flat table of (state, event, action, guard, next_state) — every transition becomes a record that can be observed, traced, and replayed.

Observability event taxonomy. A bounded list of event categories — boot, message, state, fault, security, AI inference, function. Small enough to remember. Large enough to cover everything an audit will ask for.

Error and fault policy. What constitutes a fault. Who handles it. Whether it propagates. Whether the device restarts, degrades, or signals upstream.

Five elements. A few pages each. The kind of thing a senior engineer has been carrying in their head for years — committed to paper so the codebase, the new hire, and the AI agent can all read the same source ✍️.

▸ First principle. The application architecture layer is short and concrete — five elements every team already knows, written down once.

Chapter 3. What It Unlocks for the Team

When the layer is named, the team moves at a different speed.

The new hire reads the layer doc on day one. By day three, they are extending it instead of asking which file holds the message bus. The senior engineer's mental model becomes shared property — across the whole team.

Code review becomes structural. Reviewers ask whether the change respects the lifecycle, the message contract, the FSM convention. The answer is in the doc, not in someone's head.

Audit time stays in days, rather than weeks. Safety and compliance bodies (IEC 62304, ISO 26262, IEC 61508, EU AI Act) ask for traceability between requirements, architecture, and implementation. The architecture half is the layer doc 🎯.

I have watched teams where the senior engineer moved on, and the project paused for weeks while the next person mapped the implicit conventions out of the code. I have also watched teams where the layer was written down — the senior engineer moved on, and the next person picked up the next module by week two. The artifact is the difference.

▸ First principle. Naming the layer turns one engineer's institutional memory into the whole team's shared starting point.

Chapter 4. What It Unlocks for the AI Agent 🤖

Here is the part that is genuinely new in 2026.

The AI agent reads the same layer doc the team reads. Typed message schemas, table-driven state machines, explicit lifecycle, formal contracts — these are exactly what the agent needs to generate code that fits the conventions you chose.

Without that doc, the agent does what it does best — it predicts the next plausible token. Plausible-looking code that drifts from the assumptions you carry in your head 💥.

With the doc, the agent generates a new module the same way it generates a React component. By reading the structure. By filling in the logic. The agent's work merges cleanly because it follows the same rules the human writes against.

Web frameworks taught us this lesson over the past several years. React, Next.js, Django, FastAPI — each one is a decision tree somebody locked, with typed props, route schemas, and reducer contracts. The AI agent reads the framework and produces code that fits. Embedded teams have worked above the RTOS without that same scaffolding. Naming the layer gives the AI agent the same shape the web has had ✨.

▸ First principle. What helps the human read the layer helps the AI read it. Writing it down compounds across both.

Chapter 5. The Picture in One Diagram

Here is what the stack looks like with the layer named:

┌─────────────────────────────────────────────┐
│  App modules  (sensor, motor, telemetry)    │
├─────────────────────────────────────────────┤
│  APPLICATION ARCHITECTURE LAYER             │
│   • Module lifecycle                        │
│   • Message contracts                       │
│   • State-machine convention                │
│   • Observability event taxonomy            │
│   • Error and fault policy                  │
├─────────────────────────────────────────────┤
│  RTOS / OSAL  (FreeRTOS, Zephyr, POSIX...)  │
├─────────────────────────────────────────────┤
│  HAL  (drivers, peripheral access)          │
├─────────────────────────────────────────────┤
│  Hardware  (MCU, sensors, peripherals)      │
└─────────────────────────────────────────────┘

The middle box is the artifact. The HAL and the RTOS are vendor-supplied or community-supplied. The hardware is given. The app modules are where the product lives.

The application architecture layer is the part the team owns and the part that compounds 📐.

▸ First principle. The architecture layer is the box your team controls — name it, write it down, and every box above and below it becomes easier to reason about.

Chapter 6. Why I Started Writing This Layer Down

For most of my 20+ years I worked with the application architecture layer the way most teams do — implicit, formed in code, held in a senior engineer's head 🧠.

The shift for me came when I added up the cost. Every new project, the same patterns rebuilt from scratch. Every new hire, weeks of reading code to find the message conventions. Every audit, the same effort to write the architecture diagram after the fact.

I started writing the layer down on day one, by an explicit owner, before the code commits the team to a particular interpretation. Open source. Apache 2.0. RTOS-agnostic. The contracts get committed before the implementation. The layer is structured, observable, and AI-readable by construction.

More to share on this when it is ready 😊. To anyone who already messaged asking what I am building — you know how to find me.

▸ First principle. The right time to name the architecture is week one. Writing it down is what turns implicit craft into a foundation the whole team can stand on.

Chapter 7. Pick One. Write One Page.

Here is the chapter every embedded team can act on this week 🎯.

Pick one of the five elements. Whichever your project will need first — message contracts if you have multiple modules talking, lifecycle if you are about to grow the team, observability taxonomy if you are nearing a certification gate, FSM convention if your control loop is getting tangled, fault policy if you are heading into the field.

Sit down. Write one page about it. Share it with the team and with the AI tools you use. That one page changes the conversation immediately. The next module follows it. The next refactor reads from it. The next hire onboards against it. The AI agent generating boilerplate produces code that fits.

If you take one thing from this: the architecture above the RTOS is real, it has a shape, and the earliest you name it is when it pays back the most ✨.

If you sat down today to write one page of your application layer doc — which of the five elements would you pick first?

Next: the layer is real. There is a deadline coming for every Mbed team, and the architecture above the RTOS is the part of the choice that compounds.

▸ First principle. Architecture becomes whatever the team writes down first. Name yours so the codebase, the next hire, and the AI agent all build on the same foundation.

Labeled: Opinion + Experience + Fact
(50% opinion · 30% experience · 15% fact · 5% fiction)

Sources:

(Written in collaboration with AI — I discuss, I do not outsource.)

New to this labeling? Read the framework → 20+ Years of Ideas. Articulation Is the Craft.

— Ritesh | ritzylab.com