---

Most architecture diagrams fail for a surprisingly simple reason:

They try to answer every question at once.

As systems grow, engineers tend to keep adding boxes, arrows, services, databases, protocols, and infrastructure details to the same diagram until it becomes impossible to understand.

The problem isn't that the diagram is incomplete.

The problem is that the diagram is trying to represent multiple layers of abstraction simultaneously.

---

The Realization

While designing Immyria, I kept finding myself redrawing the same architecture diagram over and over.

Each version looked different.

At first this felt like churn.

Eventually I realized something important:

I wasn't refining a diagram. I was answering a different question.

A single diagram cannot effectively answer:

• What concepts exist?
• What product capabilities exist?
• What services exist?
• How do they communicate?
• Where do they run?

These are different concerns.

Trying to combine them creates cognitive overload.

---

Five Layers of Architecture

I eventually settled on five separate architecture views.

| Layer | Question | | ------------------------ | ------------------------------ | | Information Architecture | What concepts exist? | | Product Architecture | What capabilities exist? | | Platform Architecture | How is the platform organized? | | Systems Architecture | What processes interact? | | Infrastructure Topology | Where does everything run? |

Each layer intentionally hides information that belongs to the next layer down.

---

1. Information Architecture

Information Architecture focuses on concepts.

Not services.

Not databases.

Not containers.

Concepts.

For a streaming platform those concepts might be:

• Production
• Scene
• Source
• Stream
• Destination
• Viewer

The goal is to establish shared language.

Example

Production
 ├─ Scenes
 ├─ Sources
 └─ Outputs

Output
 ├─ Stream
 └─ Recording

This diagram says nothing about implementation.

That's intentional.

---

2. Product Architecture

Product Architecture describes capabilities.

This layer answers:

What can users actually do?

Example:

• Create productions
• Invite collaborators
• Configure destinations
• Manage recordings
• Monitor stream health

At this level we still avoid discussing services.

We're describing user-facing capability boundaries.

---

3. Platform Architecture

This is where organizational structure starts emerging.

For Immyria, the platform naturally decomposed into:

┌─────────────────────┐
│ Experience Layer    │
└──────────┬──────────┘
           │
┌──────────▼──────────┐
│ SaaS Layer          │
└──────────┬──────────┘
           │
┌──────────▼──────────┐
│ Control Plane       │
└──────────┬──────────┘
           │
┌──────────▼──────────┐
│ Media Plane         │
└─────────────────────┘

This was one of the most useful diagrams I produced because it established responsibility boundaries before discussing implementation.

---

What Flows vs How It Flows

One insight that emerged during this process was that arrows should communicate more than connectivity.

Most architecture diagrams contain unlabeled arrows.

That forces readers to infer meaning.

Instead, arrows should answer:

1. What flows?
2. How does it flow?

For example:

| Flow | Transport | | ------------------- | --------- | | Production Commands | WebSocket | | Realtime State | WebSocket | | Program Stream | MPEG-TS | | Video Contribution | WebRTC | | Configuration Data | HTTP |

Notice how much information is conveyed without adding additional boxes.

---

A Better Systems Diagram

Instead of this:

App ───────────► Control
Control ───────► Media
Media ─────────► Player

Prefer this:

App
  │
  ├── Production Commands (WebSocket)
  ▼
Control Server
  │
  ├── Program Stream (MPEG-TS)
  ▼
Media Plane
  │
  ├── Playback Manifest (HTTP)
  ▼
Player Server

The difference is subtle but significant.

The second diagram explains behavior rather than structure.

---

Service Names Matter

Another lesson came from Docker decomposition.

Many projects create services named after implementation technologies.

Examples:

services:
  next:
  redis:
  caddy:

These names often become liabilities.

The implementation may change while the responsibility remains stable.

Instead:

services:
  app:
  control:
  player:
  edge-router:

The abstraction survives technology changes.

That makes architecture discussions easier.

---

Architectural Decision Records

One of the most valuable additions to the process was introducing ADRs.

An ADR captures:

• Context
• Constraints
• Alternatives
• Decision
• Consequences

Example:

# ADR-004

## Context

Player rendering is currently coupled to the control server.

## Decision

Create a dedicated program player service.

## Consequences

- Independent deployments
- Independent scaling
- Reduced coupling

Months later, this becomes architectural memory.

Without it, decisions slowly lose their rationale.

---

Lessons From Legacy Systems

Many of these ideas were shaped by previous experience.

In large systems, coupling tends to accumulate gradually.

A server that starts with one responsibility eventually gains:

• rendering
• authentication
• APIs
• scheduling
• analytics
• background jobs

Nothing feels problematic in isolation.

The problem appears years later.

Every shortcut compounds into future architecture.

---

A useful decomposition strategy:

• Platform

  • Experience Layer
  • SaaS Layer

• Runtime

  • Control Plane

    • State
    • Commands

  • Media Plane

    • Ingest
    • Processing
    • Distribution

---

Conclusion

Architecture diagrams became dramatically more useful once I stopped treating them as universal maps.

Different diagrams answer different questions.

The breakthrough wasn't creating a better diagram.

It was realizing I needed several of them.

Once Information Architecture, Product Architecture, Platform Architecture, Systems Architecture, and Infrastructure Topology were separated, complexity became much easier to reason about.

The diagrams became simpler.

Ironically, they also became more informative.

Good architecture isn't about predicting the future.

It's about preserving the ability to change your mind later.