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. Three Readers, One Spec

In 2026, every embedded codebase has at least three readers.

The team that wrote it. The next engineer to join. And the AI agent helping ship the next module.

What each of them lands on first is the application-architecture spec — how modules talk, who owns state, what happens on fault, how observability flows. When that spec is written down, all three readers move at the same speed. When it lives in a senior engineer's head, the team moves at the speed of that one engineer's availability.

The shift in 2026 is that the third reader — the AI agent — is now part of every team. The same code that gets handed to a new hire gets handed to an AI assistant. What helps the human read it helps the AI read it. The spec is the artefact that makes both possible.

▸ First principle. The application-architecture spec is the document your team's humans and your team's AI both read first. Writing it down compounds across both.

Chapter 2. The Specs Embedded Teams Already Write Beautifully

Embedded teams I have worked with across many products write meticulous hardware specs. BOM. Schematic. Layout review. DFM signoff. EVT/DVT/PVT plan.

The same teams write equally careful interface specs — USB endpoints, BLE GATT services, I²C addresses, register maps. And protocol specs — Modbus function codes, CAN message IDs, MQTT topics, payload schemas.

These are real specs. Real owners. Real review cycles. The hardware spec belongs to the hardware lead. The interface spec belongs to whoever owns the connection. The protocol spec belongs to the team integrating with the cloud. The work is careful and the artefacts are good.

Architecture is the next spec in the same family — the one that makes the codebase as readable as the schematic.

▸ First principle. Embedded teams already know how to write specs. The application-architecture spec is the next one in the same craft.

Chapter 3. Why Architecture Comes a Few Months In

Most teams write the application-architecture spec a few months into the project rather than on day one. The reason is structural, not personal.

Day-one momentum carries the team into code. The hardware is on the bench. The RTOS is picked. The first sensor reads need to come up. The architecture is forming as the code forms — module by module, decision by decision. By the time the team has space to step back, the architecture is already there, implicit in the codebase.

That works for the team that wrote it. It works less smoothly for the next reader — the new hire who joined in month four, the customer-audit team asking for a diagram, the AI agent generating boilerplate that wants to read the conventions the team chose.

The shift that pays off is doing the architecture spec on the same calendar as the hardware spec. Both get a few days of focused thought up front. Both get an owner. Both get reviewed.

▸ First principle. Architecture solidifies in code by default. Writing it down on the same calendar as the hardware spec is the move that compounds.

Chapter 4. What Compounds When the Spec Exists

When the application-architecture spec exists from week one, five things compound.

Ports become BSP swaps. The spec defines what is portable (application FBs, message contracts, FSM tables) and what is platform-specific (HAL, OSAL, drivers). A new MCU touches BSP and HAL. The application spec stays.

Observability becomes a property, not a project. The event taxonomy is a small bounded list, written once. Tracing, metrics, audit logging all read the same vocabulary. Instrumentation is a side effect of correctness, not a separate engineering pass.

AI agents read what humans wrote. The agent reads the spec the same way a senior engineer would — message contracts, FSM tables, layer boundaries. It produces code that fits the conventions the team chose. The team gets AI velocity without giving up consistency.

Certifications become trace exercises. Safety standards (IEC 62304, ISO 26262, IEC 61508) ask for traceability between requirements, architecture, and implementation. The spec is the architecture half. Audit time stays in days.

New hires onboard against a document. Week one of a new engineer is reading the spec, not following one engineer around. The institutional memory lives in the artefact, available to everyone — including the AI agent.

▸ First principle. Writing the architecture down is one of the highest-return moves an embedded team can make in week one.

Chapter 5. What the Spec Actually Contains

A working application-architecture spec is short. Six elements, each worth one section in the doc.

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

Module lifecycle. The states every module passes through: created, initialised, running, faulted, stopped. Who drives those transitions. What guarantees the framework provides at each stage. Boot ordering follows from the lifecycle.

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, replayed.

Layer boundaries. What belongs in HAL (hardware peripheral access). What belongs in OSAL (OS primitives). What belongs in module code (domain logic). What belongs in the framework. The boundary rules are short and they hold across every team member.

Observability event taxonomy. A bounded list of event categories — boot, message, state, fault, security, AI inference, function. Small enough to remember and large enough to cover everything an audit needs.

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

These six fit on a few pages. Each one is the kind of thing the team already has in their heads — written down once, before the code commits the team to a particular interpretation.

▸ First principle. The spec is short. Each element is something the team already knows — committed to paper so the codebase, the next hire, and the AI agent can all read it.

Chapter 6. Why I Started Writing It Down

Across many years of shipping embedded products, I came to recognise the pattern. Hardware spec — careful. Interface spec — careful. Protocol spec — careful. Architecture spec — usually a few months in, after the code had already locked in the implicit choices.

The shift for me was treating the architecture spec as the next member of the same family — written on the same calendar as the hardware spec, by an explicit owner, before the code committed the team to any particular interpretation.

I started writing one. Open source. The contracts are committed before the implementation. RTOS-agnostic, structured, observable from day one. AI-readable by construction — every FB carries machine-readable metadata, every message has a typed schema, every FSM is a table the agent can parse.

Architecture compounds when somebody writes it down. The compounding is bigger now than it was five years ago — because the AI reading the spec is part of the team, not a separate workflow.

▸ First principle. Structure becomes a spec when someone sits down and writes it. The earlier that happens, the more the code, the next hire, and the AI agent all follow from the same source.

Chapter 7. Pick One Element. Write One Page.

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

Pick one element from the six. Whichever one 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. 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. The next module written follows it. The next refactor reads from it. The next hire onboards against it. The AI agent generating boilerplate produces code that fits the conventions you chose. Each motion the team makes after that page is built on top of it.

What's the one architectural contract you'd write down first if you sat down to spec your application architecture today?

Next: the layer above the RTOS that gets named on day one — and what that name unlocks for the team and the agent.

▸ First principle. The architecture becomes whatever gets written down first. Write yours so the team, the next hire, and the AI agent can all read it.

—
Opinion + Experience + Fact (50% opinion · 30% experience · 15% fact · 5% fiction)
Sources: Previous post — AI Can Write Your Frontend. It Can't Write Your Firmware.
(Written in collaboration with AI — I discuss, I don't outsource.)

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

— Ritesh | ritzylab.com