DEV Community

bayu priatno
bayu priatno

Posted on

NEIR: The Intermediate Representation at the Center of NAEOS

#ai #go #softwareengineering #productivity

In the previous article, we looked at the architecture behind NAEOS and the idea of treating software engineering as a pipeline rather than a collection of disconnected tools.

At the center of that pipeline is a concept that deserves a deeper look:

NEIR — NAEOS Engineering Intermediate Representation.

If NAEOS is an engineering operating system, NEIR is one of its most important internal abstractions.

It sits between human-readable engineering specifications and the systems that consume them.

Specification
      │
      ▼
   Parsing
      │
      ▼
 Normalization
      │
      ▼
 Resolution
      │
      ▼
     NEIR
      │
 ┌────┼───────────────┐
 ▼    ▼               ▼
AI   Validation    Generation
Enter fullscreen mode Exit fullscreen mode

The purpose is not simply to create another data structure.

The purpose is to create a shared semantic model of an engineering system.

The Problem With Direct Specification-to-Code Generation

A simple generator can work like this:

YAML
 │
 ▼
Generator
 │
 ▼
Source Code
Enter fullscreen mode Exit fullscreen mode

This works for small projects.

But software engineering becomes much more complicated when the specification describes:

  • multiple modules
  • services
  • APIs
  • databases
  • infrastructure
  • security requirements
  • deployment
  • testing
  • AI agents
  • architectural constraints

Now imagine adding multiple consumers:

Specification
 ├──→ Code Generator
 ├──→ Documentation Generator
 ├──→ AI Agent
 ├──→ Validator
 ├──→ Infrastructure Generator
 └──→ Architecture Analyzer
Enter fullscreen mode Exit fullscreen mode

Every consumer has to understand the specification independently.

That creates a problem.

Each subsystem develops its own interpretation of the system.

Eventually:

Specification
      │
      ├── Generator interpretation
      ├── Validator interpretation
      ├── AI interpretation
      ├── Documentation interpretation
      └── Infrastructure interpretation
Enter fullscreen mode Exit fullscreen mode

These interpretations can diverge.

This is the same class of problem compiler architectures have addressed through intermediate representations.

The Compiler Analogy

A traditional compiler does not need every backend to understand every source language.

Instead, source code is transformed into an intermediate representation.

Source Code
    │
    ▼
   AST
    │
    ▼
Intermediate Representation
    │
 ┌──┼──────┐
 ▼  ▼      ▼
x86 ARM   WASM
Enter fullscreen mode Exit fullscreen mode

The IR creates a stable boundary.

NAEOS applies a similar architectural idea to engineering systems.

Engineering Specification
          │
          ▼
        NEIR
          │
 ┌────────┼────────┐
 ▼        ▼        ▼
Code     AI      Governance
Gen.     Context   Validation
Enter fullscreen mode Exit fullscreen mode

The difference is that NEIR is not a representation of a programming language.

It is a representation of an engineering system.

What Does NEIR Represent?

The NAEOS repository describes NEIR around engineering concepts such as:

Project
Architecture
Domain
Module
Component
Service
API
Storage
Infrastructure
Security
AI
Documentation
Deployment
Testing
Metadata
Enter fullscreen mode Exit fullscreen mode

That distinction is important.

Consider this:

func CreatePayment() error {
    // implementation
}
Enter fullscreen mode Exit fullscreen mode

The function itself is implementation detail.

But the engineering model might need to know:

Payment Service
 ├── belongs to Payments Domain
 ├── exposes POST /payments
 ├── depends on Identity
 ├── persists data in PostgreSQL
 ├── requires authentication
 └── must satisfy architectural policies
Enter fullscreen mode Exit fullscreen mode

NEIR represents the latter.

The implementation can change.

The engineering intent remains.

Engineering Intent vs Implementation

This distinction is fundamental.

Consider:

Intent
──────

There must be a Payment service.

The service exposes an HTTP API.

The service requires authentication.

The service uses PostgreSQL.
Enter fullscreen mode Exit fullscreen mode

That intent can produce multiple implementations.

                 Payment Service
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
       Go          TypeScript       Rust
        │              │              │
        ▼              ▼              ▼
 Implementation  Implementation  Implementation
Enter fullscreen mode Exit fullscreen mode

The implementation language is not the engineering identity of the service.

This separation gives NAEOS a much more useful abstraction boundary.

NEIR as a Semantic Boundary

A useful way to think about NEIR is:

NEIR separates what the engineering system means from how a particular tool implements it.

                 Engineering Intent
                         │
                         ▼
                       NEIR
                         │
       ┌─────────────────┼─────────────────┐
       ▼                 ▼                 ▼
    Generator         Validator         AI Compiler
       │                 │                 │
       ▼                 ▼                 ▼
    Source Code       Policy Result      AI Context
Enter fullscreen mode Exit fullscreen mode

This prevents downstream components from becoming tightly coupled to the original specification format.

Why Not Just Use the AST?

An obvious question is:

Why not simply use the parser's AST?

Because an AST answers a different question.

An AST primarily represents the syntactic structure of the input.

For example:

services:
  - name: payments
    port: 8080
Enter fullscreen mode Exit fullscreen mode

The AST tells us how that document was structured.

But the engineering system needs to understand:

Service
  name = payments
  protocol = HTTP
  port = 8080
  dependencies = [...]
  policies = [...]
  deployment = [...]
Enter fullscreen mode Exit fullscreen mode

The difference is:

AST
↓
What did the document say?

NEIR
↓
What does the engineering system mean?
Enter fullscreen mode Exit fullscreen mode

That semantic distinction is what makes an IR useful.

From Specification to NEIR

The transformation can be viewed as several stages.

             Raw Specification
                     │
                     ▼
                  Parser
                     │
                     ▼
                    AST
                     │
                     ▼
               Normalization
                     │
                     ▼
                 Resolution
                     │
                     ▼
                    NEIR
Enter fullscreen mode Exit fullscreen mode

Each stage has a different responsibility.

Parser

Understand syntax.

Normalizer

Create canonical representations.

Resolver

Resolve relationships and references.

NEIR

Represent the resulting engineering system.

This separation makes the pipeline easier to reason about and test.

Relationships Matter

One of the biggest advantages of an engineering IR is that relationships become explicit.

For example:

Identity
   ▲
   │ dependency
   │
Payments
   │
   ├── exposes → Payment API
   │
   ├── stores → Payment Database
   │
   └── deployed-on → Kubernetes
Enter fullscreen mode Exit fullscreen mode

A flat configuration file may contain all of this information.

But NEIR can represent these relationships explicitly.

This makes graph-oriented operations possible.

For example:

Find all services depending on Identity.

Find all APIs exposed by Payments.

Find all components using PostgreSQL.

Find all resources violating a policy.

Find all artifacts generated from a specific specification node.
Enter fullscreen mode Exit fullscreen mode

These are engineering queries, not text-processing operations.

NEIR as a Graph

Conceptually, NEIR can be understood as an engineering graph.

                 ┌─────────────┐
                 │   Project   │
                 └──────┬──────┘
                        │
                        ▼
                ┌───────────────┐
                │ Architecture  │
                └───────┬───────┘
                        │
             ┌──────────┴──────────┐
             ▼                     ▼
        ┌─────────┐           ┌─────────┐
        │ Identity│           │Payments │
        └────┬────┘           └────┬────┘
             │                     │
             │              ┌──────┼──────┐
             │              ▼      ▼      ▼
             │             API   Storage Service
             │
             └──────── dependency ────────►
Enter fullscreen mode Exit fullscreen mode

Once engineering information is represented as a graph, many capabilities become possible.

Validation Becomes Graph Reasoning

Suppose the architecture defines:

Domain
  ↓
Application
  ↓
Infrastructure
Enter fullscreen mode Exit fullscreen mode

and prohibits:

Domain
  ↓
Infrastructure
Enter fullscreen mode Exit fullscreen mode

The validator can inspect the graph.

Domain ────────────X──────────> Infrastructure
Enter fullscreen mode Exit fullscreen mode

Instead of relying on a human reviewer to notice the violation, the rule can become executable.

Conceptually:

NEIR
 │
 ▼
Policy Engine
 │
 ▼
Graph Evaluation
 │
 ├── valid
 └── violation
Enter fullscreen mode Exit fullscreen mode

This is one of the strongest reasons to maintain a semantic engineering model.

Generation Becomes Model Consumption

Generators can also consume NEIR.

For example:

NEIR
 │
 ├── Service
 │     ├── API
 │     ├── Dependencies
 │     └── Storage
 │
 ▼
Go Generator
 │
 ▼
Go Project
Enter fullscreen mode Exit fullscreen mode

Another generator can consume the same model:

NEIR
 │
 ▼
TypeScript Generator
 │
 ▼
TypeScript Project
Enter fullscreen mode Exit fullscreen mode

The engineering model remains the same.

Only the target changes.

AI Context Becomes Model-Derived

The same principle applies to AI.

Instead of manually maintaining a massive collection of instructions:

README
CLAUDE.md
Cursor Rules
Copilot Instructions
Developer Notes
Architecture Docs
Enter fullscreen mode Exit fullscreen mode

NAEOS can derive AI context from the engineering model.

Conceptually:

NEIR
 │
 ▼
AI Context Compiler
 │
 ├──→ Claude Code
 ├──→ Cursor
 ├──→ GitHub Copilot
 ├──→ Codex
 ├──→ Gemini CLI
 └──→ Other Agents
Enter fullscreen mode Exit fullscreen mode

The repository currently contains adapters for several AI coding environments, making this model particularly relevant to the NAEOS architecture. (github.com)

The important idea is not the individual adapter.

It is the common source.

                NEIR
                 │
                 ▼
          AI Context Model
                 │
       ┌─────────┼─────────┐
       ▼         ▼         ▼
    Agent A   Agent B   Agent C
Enter fullscreen mode Exit fullscreen mode

Different agents can consume the same engineering truth.

One Model, Multiple Outputs

This gives NAEOS an important property:

                         NEIR
                          │
       ┌──────────────────┼──────────────────┐
       │                  │                  │
       ▼                  ▼                  ▼
    Source Code      Documentation       AI Context
       │                  │                  │
       ▼                  ▼                  ▼
    Artifacts          Artifacts          Instructions
Enter fullscreen mode Exit fullscreen mode

The system no longer needs every output to be manually synchronized.

They can be derived from the same model.

Traceability

Another important consequence is traceability.

Imagine a generated file:

internal/payment/service.go
Enter fullscreen mode Exit fullscreen mode

The system should ideally be able to answer:

Where did this artifact come from?

Which specification defined it?

Which NEIR node generated it?

Which policies were evaluated?

Which generator produced it?

Which version of the engineering model was used?
Enter fullscreen mode Exit fullscreen mode

This creates a chain:

Specification
     │
     ▼
    NEIR
     │
     ▼
Generation Plan
     │
     ▼
Artifact
Enter fullscreen mode Exit fullscreen mode

That chain becomes valuable for debugging, auditing, governance, and reproducibility.

Reproducibility

A shared intermediate representation also creates a better foundation for reproducibility.

Instead of:

Prompt
  ↓
AI
  ↓
Different result tomorrow
Enter fullscreen mode Exit fullscreen mode

the target becomes:

Specification
     +
Schema
     +
NEIR
     +
Policies
     +
Generator Version
     ↓
Engineering Artifact
Enter fullscreen mode Exit fullscreen mode

AI can still participate.

But AI is no longer required to reconstruct the entire engineering context from scratch every time.

The Trade-Off

NEIR is not free.

Introducing an intermediate representation adds:

  • schema complexity
  • transformation logic
  • versioning concerns
  • migration requirements
  • additional validation
  • more runtime components

For a small project, this may be unnecessary.

If you only need:

config → template → code
Enter fullscreen mode Exit fullscreen mode

a conventional generator is probably enough.

The value appears when the engineering system becomes complex.

When there are many consumers of the same engineering information, the intermediate representation becomes an architectural asset.

NEIR Versioning

An engineering IR also introduces a critical question:

What happens when the model evolves?

Suppose version 1 contains:

Service
API
Database
Enter fullscreen mode Exit fullscreen mode

and version 2 adds:

Service
API
Database
Event
SecurityPolicy
Deployment
Enter fullscreen mode Exit fullscreen mode

Consumers need compatibility strategies.

This makes schema versioning important.

A mature IR needs to consider:

Backward Compatibility
Forward Compatibility
Migration
Validation
Deprecation
Version Negotiation
Enter fullscreen mode Exit fullscreen mode

This is not unique to NAEOS.

It is a fundamental property of any long-lived intermediate representation.

The Architectural Payoff

The real benefit of NEIR is not that it makes YAML easier to parse.

It creates a stable boundary between engineering intent and engineering execution.

                 HUMAN INTENT
                      │
                      ▼
                Specification
                      │
                      ▼
                     NEIR
                      │
       ┌──────────────┼──────────────┐
       ▼              ▼              ▼
   Governance       AI             Build
       │              │              │
       ▼              ▼              ▼
    Policies       Context        Artifacts
Enter fullscreen mode Exit fullscreen mode

That boundary allows NAEOS to evolve without forcing every subsystem to understand every representation.

NEIR and the Engineering Operating System

This brings us back to the larger NAEOS architecture.

An operating system provides abstractions.

Applications do not need to directly understand every hardware detail.

Similarly, an engineering operating system should provide abstractions that allow engineering tools to work against a common system model.

In this analogy:

Operating System
      │
      ├── Process Model
      ├── Resource Model
      ├── Security Model
      └── System APIs
Enter fullscreen mode Exit fullscreen mode

NAEOS moves toward:

Engineering Operating System
      │
      ├── Engineering Model
      ├── Policy Model
      ├── Execution Model
      ├── Artifact Model
      └── AI Context Model
Enter fullscreen mode Exit fullscreen mode

NEIR sits near the center of this architecture.

The Core Idea

The most important idea can be summarized like this:

Code is an artifact. The engineering system is the model that produces and governs those artifacts.

That changes the role of AI as well.

AI does not need to become the source of truth.

AI can become one of the execution engines operating against the source of truth.

                     Engineering Model
                            │
                ┌───────────┼───────────┐
                ▼           ▼           ▼
             Humans        AI        Automation
                │           │           │
                └───────────┼───────────┘
                            ▼
                        Artifacts
Enter fullscreen mode Exit fullscreen mode

That is the architectural direction NAEOS is exploring.

Conclusion

NEIR is more than an internal data structure.

It is an architectural boundary.

It allows NAEOS to connect:

  • specifications
  • architecture
  • governance
  • validation
  • scheduling
  • generation
  • AI agents
  • documentation
  • deployment
  • testing
  • artifacts

through a shared engineering representation.

The resulting pipeline looks like:

Intent
  ↓
Specification
  ↓
Parsing
  ↓
Normalization
  ↓
Resolution
  ↓
NEIR
  ↓
Validation + Governance
  ↓
Scheduling
  ↓
Generation / AI
  ↓
Artifacts
Enter fullscreen mode Exit fullscreen mode

The key question is no longer:

"Which AI coding tool should we use?"

It becomes:

"What engineering model should every coding tool operate against?"

That is the problem NEIR is designed to address.

Next: Part 3

From Specification to Software: Inside the NAEOS Compilation Pipeline

In the next article, we will move from the NEIR model into execution and examine how NAEOS transforms an engineering model into a validated and schedulable execution plan.

Top comments (0)