DEV Community

Cover image for Inside NAEOS: Building an Engineering Operating System Around a Single Source of Truth
bayu priatno
bayu priatno

Posted on

Inside NAEOS: Building an Engineering Operating System Around a Single Source of Truth

#ai #softwareengineering #go #opensource

Most AI coding tools start with code.

NAEOS starts one layer earlier: the engineering specification.

The idea behind NAEOS is simple:

Specify the system once. Build, validate, and evolve it through a consistent engineering pipeline.

But implementing that idea requires more than a project generator.

It requires an architecture that can understand engineering intent, transform it into a machine-readable model, validate it against rules, produce execution plans, generate artifacts, and keep AI agents aligned with the same system model.

This article explains the architecture behind NAEOS and why it is designed more like an engineering operating system than a traditional code generator.

The Problem With Code-First AI Engineering

Modern AI coding agents are remarkably capable.

Give an agent a prompt such as:

Build a payment service with authentication,
PostgreSQL, REST APIs, and a background worker.
Enter fullscreen mode Exit fullscreen mode

It can produce a significant amount of code.

But there is a deeper problem.

Where does the engineering intent live after the code has been generated?

Consider a system with:

  • 20 modules
  • 15 services
  • 40 APIs
  • multiple databases
  • infrastructure dependencies
  • security requirements
  • architectural constraints
  • multiple AI agents

If the system is represented primarily through source code and prompts, the engineering model becomes fragmented.

You may have:

Source Code
Documentation
Architecture Diagrams
Configuration
AI Instructions
CI/CD Configuration
Infrastructure
Developer Knowledge
Enter fullscreen mode Exit fullscreen mode

Each contains part of the truth.

The result is engineering drift.

A Different Model

NAEOS introduces a different abstraction:

                 Engineering Specification
                           │
                           ▼
                     NAEOS Pipeline
                           │
              ┌────────────┴────────────┐
              │                         │
              ▼                         ▼
            NEIR                    Governance
              │                         │
              └────────────┬────────────┘
                           ▼
                     Execution Plan
                           │
             ┌─────────────┼─────────────┐
             ▼             ▼             ▼
          Generator      AI Compiler    Context
             │             │             │
             └─────────────┴─────────────┘
                           │
                           ▼
                       Artifacts
Enter fullscreen mode Exit fullscreen mode

The specification becomes the starting point.

Code, AI instructions, documentation, and other artifacts become outputs derived from the engineering model.

This is the fundamental architectural decision behind NAEOS.

The NAEOS Pipeline

At the core of NAEOS is a staged engineering pipeline:

Specification
      │
      ▼
    Parser
      │
      ▼
  Normalizer
      │
      ▼
   Resolver
      │
      ▼
     NEIR
      │
      ▼
   Validator
      │
      ▼
   Scheduler
      │
      ▼
   Generators
      │
      ├───────────────┐
      ▼               ▼
   Artifacts       AI Context
Enter fullscreen mode Exit fullscreen mode

The current implementation exposes these responsibilities as separate components in the repository, including specification parsing, normalization, resolution, NEIR construction, validation, scheduling, generation, governance, and AI compilation.

The important property is separation of concerns.

A parser should not decide architectural policy.

A generator should not redefine the system model.

An AI adapter should not become the source of truth.

Each stage has a specific responsibility.

1. Specification

Everything starts with a declarative specification.

For example:

project: payments

architecture:
  pattern: hexagonal

modules:
  - name: identity

  - name: payments
    dependencies:
      - identity

services:
  - name: api
    kind: http
    port: 8080

generation:
  languages:
    - go
    - typescript
Enter fullscreen mode Exit fullscreen mode

The specification describes what the system is supposed to be.

It does not need to contain every implementation detail.

The goal is to establish a structured engineering intent that downstream components can understand.

NAEOS Specification Language v2 also supports features such as variable interpolation, environment variables, references, multi-file composition, functions, conditionals, and schema versioning.

2. Parser

The parser converts the external representation into an internal structure.

Conceptually:

YAML / JSON / HCL
        │
        ▼
      Parser
        │
        ▼
   Structured Data
Enter fullscreen mode Exit fullscreen mode

This layer should answer:

Is this specification syntactically understandable?

It should not answer:

Is this architecture acceptable?

That distinction becomes important as the system grows.

3. Normalization

Different specifications can express the same concept in different ways.

Normalization creates a consistent representation.

Input A ─┐
         ├──> Normalizer ──> Canonical Model
Input B ─┘
Enter fullscreen mode Exit fullscreen mode

For example, aliases, defaults, optional fields, and equivalent representations can be normalized before deeper processing.

This makes downstream processing significantly more predictable.

4. Resolution

Specifications frequently contain relationships.

For example:

modules:
  - name: payments
    dependencies:
      - identity
Enter fullscreen mode Exit fullscreen mode

The resolver must understand what identity refers to.

The same principle applies to:

  • references
  • dependencies
  • profiles
  • templates
  • configuration
  • imported specifications

Conceptually:

Normalized Specification
          │
          ▼
       Resolver
          │
          ▼
Resolved Engineering Model
Enter fullscreen mode Exit fullscreen mode

5. NEIR

This is where NAEOS becomes particularly interesting.

NEIR — NAEOS Engineering Intermediate Representation — is the central engineering model.

Instead of allowing every subsystem to interpret the original specification independently, NAEOS creates a shared intermediate representation.

                Specification
                      │
                      ▼
              ┌──────────────┐
              │     NEIR     │
              └──────────────┘
                 │    │    │
        ┌────────┘    │    └────────┐
        ▼             ▼             ▼
    Generator      Validator     AI Compiler
        │             │             │
        ▼             ▼             ▼
      Code          Policy       Instructions
Enter fullscreen mode Exit fullscreen mode

The repository describes NEIR as representing the broader engineering system, including project, architecture, domain, modules, components, services, APIs, storage, infrastructure, security, AI, documentation, deployment, testing, and metadata.

This gives NAEOS a common semantic layer.

Why an Intermediate Representation Matters

Compiler engineers have used intermediate representations for decades.

A compiler does not normally translate every source language directly into every machine architecture.

Instead:

Source
  │
  ▼
AST
  │
  ▼
Intermediate Representation
  │
  ▼
Optimization
  │
  ▼
Target
Enter fullscreen mode Exit fullscreen mode

NAEOS applies a similar idea to software engineering.

Instead of:

Specification → Generator
Specification → AI Agent
Specification → Documentation
Specification → Validation
Enter fullscreen mode Exit fullscreen mode

we can have:

                    Specification
                          │
                          ▼
                         NEIR
                 ┌────────┼────────┐
                 ▼        ▼        ▼
             Generator Validator AI Compiler
                 │        │        │
                 ▼        ▼        ▼
               Code     Policy   AI Context
Enter fullscreen mode Exit fullscreen mode

The intermediate representation becomes the common language between engineering capabilities.

6. Validation

Once the system has been represented as NEIR, NAEOS can reason about it.

For example:

Module A
   │
   └── depends on → Module B
Enter fullscreen mode Exit fullscreen mode

The validator can detect architectural problems such as:

  • circular dependencies
  • invalid module boundaries
  • conflicting ports
  • invalid references
  • policy violations

This is fundamentally different from asking an AI model:

"Does this architecture look correct?"

The validator can enforce deterministic rules.

7. Scheduling

Engineering operations often form a dependency graph.

For example:

Database
   │
   ▼
Domain
   │
   ▼
Application
   │
   ▼
API
   │
   ▼
Tests
Enter fullscreen mode Exit fullscreen mode

NAEOS can represent execution as a DAG:

Task A ─────┐
            ▼
          Task C
            ▲
Task B ─────┘
Enter fullscreen mode Exit fullscreen mode

This allows independent operations to execute independently while respecting dependencies.

The repository describes the scheduler as DAG-based task scheduling.

8. Generation

Once the system has passed validation, generators can produce artifacts.

The important distinction is:

The generator consumes the engineering model.

It does not redefine the engineering model.

Conceptually:

                 NEIR
                  │
       ┌──────────┼──────────┐
       ▼          ▼          ▼
      Go      TypeScript   Python
       │          │          │
       ▼          ▼          ▼
    Artifact   Artifact   Artifact
Enter fullscreen mode Exit fullscreen mode

The current NAEOS repository lists generators for multiple languages, including Go, TypeScript, Python, Java, and Rust.

9. AI Compilation

This is another important architectural boundary.

NAEOS does not have to replace AI coding agents.

Instead, it can compile engineering context into instructions understood by different AI development environments.

The architecture becomes:

                    NEIR
                      │
                      ▼
                AI Compiler
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
   Claude Code     Cursor       Copilot
        │             │             │
        ▼             ▼             ▼
    Instructions   Rules        Instructions
Enter fullscreen mode Exit fullscreen mode

The repository currently includes adapters for tools such as GitHub Copilot, Claude Code, Cursor, Gemini CLI, Codex, OpenCode, and Windsurf.

This leads to an important architectural principle:

AI agents should consume the engineering model rather than become the engineering model.

Prompt Is Not Policy

This distinction becomes critical when AI agents can modify real systems.

A prompt might say:

Do not modify the payment database.
Enter fullscreen mode Exit fullscreen mode

But a prompt is not a reliable security boundary.

A stronger architecture is:

AI Agent
   │
   │ request
   ▼
NAEOS Control Layer
   │
   ├── Policy
   ├── Validation
   ├── Authorization
   └── Audit
   │
   ▼
Allowed Action
Enter fullscreen mode Exit fullscreen mode

The agent can be highly capable without being given unrestricted authority.

This is one of the reasons an engineering operating system needs a control layer rather than simply an AI interface.

Governance as an Engineering Layer

NAEOS also treats governance as part of the engineering pipeline.

Conceptually:

Specification
      │
      ▼
     NEIR
      │
      ▼
   Policies
      │
      ▼
 Validation
      │
      ▼
 Artifact Review
      │
      ▼
   Approved Output
Enter fullscreen mode Exit fullscreen mode

The repository currently includes policy evaluation, artifact review, and audit-trail capabilities.

This changes governance from documentation into something closer to an executable engineering mechanism.

Instead of:

"Our architecture follows these rules."

the system can move toward:

"These rules are machine-readable and evaluated during engineering execution."

The Kernel

Underneath these capabilities is the NAEOS kernel.

The repository describes the kernel as providing foundational runtime services such as:

  • service registry
  • event bus
  • telemetry
  • lifecycle management

This gives the higher-level pipeline a common runtime foundation.

The resulting architecture can be viewed as:

┌───────────────────────────────────────────┐
│              NAEOS Applications            │
│                                           │
│ CLI │ AI │ Generator │ Governance │ MCP   │
├───────────────────────────────────────────┤
│              Engineering Pipeline          │
│                                           │
│ Parse → Normalize → Resolve → NEIR        │
│             → Validate → Schedule         │
├───────────────────────────────────────────┤
│                   Kernel                   │
│                                           │
│ Registry │ Events │ Telemetry │ Lifecycle │
├───────────────────────────────────────────┤
│            Runtime / Platform              │
└───────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Extensibility

An engineering operating system cannot be closed around a single implementation strategy.

NAEOS therefore exposes extensibility through plugins, profiles, templates, marketplace components, and other adapters.

The repository includes a plugin SDK with a WASM runtime, profile and plugin marketplace capabilities, and multiple built-in industry profiles.

The architectural goal is:

                  NAEOS Core
                      │
       ┌──────────────┼──────────────┐
       ▼              ▼              ▼
    Plugins         Profiles      Adapters
       │              │              │
       ▼              ▼              ▼
      WASM       Domain Context    AI Tools
Enter fullscreen mode Exit fullscreen mode

The core remains stable while capabilities can evolve around it.

The Full Architecture

Putting the pieces together:

                         Developer
                             │
                             ▼
                    Engineering Spec
                             │
                             ▼
                         Parser
                             │
                             ▼
                       Normalizer
                             │
                             ▼
                         Resolver
                             │
                             ▼
                           NEIR
                             │
            ┌────────────────┼────────────────┐
            │                │                │
            ▼                ▼                ▼
        Governance       Validation       Context
            │                │                │
            └────────────────┼────────────────┘
                             ▼
                         Scheduler
                             │
               ┌─────────────┼─────────────┐
               │             │             │
               ▼             ▼             ▼
           Generator     AI Compiler     Plugins
               │             │             │
               ▼             ▼             ▼
             Code        AI Context     Extensions
               │             │             │
               └─────────────┼─────────────┘
                             ▼
                         Artifacts
                             │
                             ▼
                       Verification
                             │
                             ▼
                       Engineering
                         System
Enter fullscreen mode Exit fullscreen mode

This is the architectural idea behind NAEOS.

Not:

Prompt → Code
Enter fullscreen mode Exit fullscreen mode

But:

Intent
  ↓
Specification
  ↓
Engineering Model
  ↓
Governance
  ↓
Execution
  ↓
Artifacts
  ↓
Verification
Enter fullscreen mode Exit fullscreen mode

Why This Architecture Matters

AI has dramatically reduced the cost of generating code.

But code generation is only one part of software engineering.

Large engineering systems still require:

  • architecture
  • constraints
  • dependency management
  • validation
  • security
  • governance
  • reproducibility
  • documentation
  • testing
  • traceability
  • controlled execution

The challenge is therefore shifting.

The question is no longer:

"Can AI write the code?"

The more important question becomes:

"Can we give AI enough capability to build software without losing control of the engineering system?"

NAEOS explores one possible answer.

Create a machine-readable engineering model.

Make it the common source of truth.

Put deterministic validation and governance around it.

Then allow generators, AI agents, plugins, and other tools to operate against that model.

The Core Principle

The architecture can ultimately be summarized in one sentence:

AI should accelerate engineering execution, but the engineering system should remain the authority.

That distinction is at the center of NAEOS.

The project is open source and actively evolving, with the current repository documenting the implementation, architecture, specifications, CLI, governance, AI integration, plugin system, and runtime components.

If this direction is interesting, the next question is much more technical:

How exactly does NEIR work?

That will be the subject of the next article.

Next

Part 2 — NEIR: The Intermediate Representation at the Center of NAEOS

We will go inside the NEIR model, examine why an engineering IR is necessary, and explore how one representation can become the foundation for validation, generation, governance, and AI context.

Top comments (0)