Compiler Architecture

The Prodara compiler processes .prd source files through 15 distinct phases, producing a deterministic Product Graph. Each phase is a separate module with typed inputs and outputs.

Design Principles

  • Phase Separation - Each phase has a single responsibility and typed contract
  • Diagnostic Accumulation - Errors are collected in a DiagnosticBag, never thrown as exceptions
  • Deterministic Output - Same input always produces the same graph (except compiled_at)
  • Agent-Friendly - All output is structured JSON with stable contracts

The 15 Phases

1

Discovery

Scans the file system for .prd source files and resolves module relationships.

2

Lexer

Tokenizes source text into a stream of typed tokens (keywords, identifiers, literals, punctuation).

3

Parser

Builds an Abstract Syntax Tree (AST) from the token stream.

4

Binder

Creates a symbol table linking declarations to their scopes and resolving references.

5

Type Checker

Validates type compatibility across fields, workflows, and references.

6

Graph Builder

Constructs the Product Graph from the bound and type-checked AST.

7

Planner

Diffs graphs and produces incremental plans with impact propagation.

8

Spec Test Runner

Executes specification-level tests against the Product Graph.

9

Runtime Resolution

Resolves runtime configurations and environment-specific settings.

10

Build State

Manages persistent build state for incremental compilation.

11

Generator Contracts

Produces typed contracts for downstream code generators.

12

Graph Validator

Validates structural integrity and semantic rules of the Product Graph.

13

Registry Resolution

Resolves external packages and presets from the registry.

14

Build Orchestration

Coordinates the full build pipeline and produces the final BuildSummary.

15

Configuration

Manages compiler configuration and feature flags.

Semantic Node IDs

Every node in the Product Graph has a stable semantic ID following the pattern: 

<module>.<kind>.<name>

// Examples:
core.entity.user
billing.workflow.create_invoice
auth.surface.login_form

Build State

The compiler persists build state in a .prodara/ directory for incremental compilation. This includes the previous graph, plan artifacts, and build metadata.

Beyond Compilation

After the core 15-phase pipeline, Prodara runs additional high-level phases:

  • Workflow Engine - Orchestrates specify → clarify → plan → implement cycles. See Custom Workflows.
  • Reviewer Pipeline - 9 built-in reviewer agents inspect the plan from different perspectives. See Reviewers & Constitution.
  • Extension System - Custom generators, validators, and reviewers loaded at build time. See Extensions & Presets.
  • Proposal System - Stage changes in isolation for review. See Proposals & Changes.