FROG IDE Architecture

Architecture and responsibilities of a FROG development environment
FROG — Free Open Graphical Language

1. Overview
2. Document Role
3. Repository Navigation
4. Scope of this Document
5. Relation with Other Specifications
6. Responsibility Boundaries
7. High-Level Architecture
8. Current Documents
9. Main Components
10. IDE Shell
11. Diagram Editor
12. Front Panel Editor
13. FROG Program Model
14. Relation with FROG Expression
15. Execution Integration Boundary
16. Palette
17. Express Authoring
18. Execution Observability
19. Debugging
20. Probes
21. Watch
22. Snippets
23. Design Principles
24. Repository Direction
25. Summary

1. Overview

The FROG IDE is the graphical development environment used to design, edit, validate, inspect, and debug programs written in the FROG graphical dataflow language. A conforming IDE MAY additionally integrate execution-facing services such as validation pipelines, execution preparation, compiler services, runtime services, or equivalent subsystems.

A FROG IDE does not treat the saved .frog file as the live editable artifact. Instead, it loads and maintains an internal FROG Program Model, which is the canonical editable in-memory representation used during authoring. The canonical saved source file remains the FROG Expression, defined in Expression/.

Interactive inspection and debugging are not performed directly on raw serialized source. They are performed on a live execution derived from validated canonical program content, through a source-aligned observability layer that allows the IDE to project runtime activity back onto diagram-visible, front-panel-visible, and other source-meaningful objects.

A conforming IDE MAY expose authoring-facing views, shortcuts, aliases, assistant-driven insertion flows, guided entries, and other conveniences that are more ergonomic than the raw canonical source representation. However, those conveniences do not become new language constructs by themselves. The IDE remains responsible for preserving canonical source identity and for keeping semantic ownership in the specification layers that define it normatively.

This includes Express authoring: an IDE MAY provide guided, configurable, task-oriented insertion experiences for common operations, but those experiences MUST normalize to canonical FROG content already owned by Expression/, Language/, Libraries/, and Profiles/ where relevant.

This document defines how a conforming FROG IDE is organized as an authoring, discoverability, observability, debugging, inspection, and transport environment without making the language dependent on one particular editor implementation.

Repository architecture around IDE/

Expression/   -> canonical source form
Language/     -> normative execution semantics
Libraries/    -> intrinsic primitive vocabularies
Profiles/     -> optional standardized capability families
IR/           -> canonical execution-facing representation and downstream boundaries
IDE/          -> authoring, discoverability, observability, debugging, inspection

IDE/ own tooling behavior.
IDE/ do not own source meaning or execution meaning.

Mental model in one glance

User edits in the IDE
        |
        v
IDE maintains Program Model
        |
        v
Program Model serializes to canonical .frog source
        |
        v
validated canonical content is handed to execution-facing systems
        |
        v
runtime activity comes back through source-aligned observability
        |
        +-> debugging
        +-> probes
        \-> watches

2. Document Role

This document is the architectural entry point of the IDE/ repository family. It explains:

what the IDE layer owns,
what it does not own,
how the documents inside IDE/ are organized,
how IDE-facing concerns relate to Expression/, Language/, IR/, Libraries/, and Profiles/.

It should be read first when navigating the IDE-facing documentation. The other documents in IDE/ refine individual subdomains such as palette behavior, observability, debugging, probes, watches, and snippets.

The current IDE-facing repository family is organized as follows:

IDE/
├── Readme.md
│   -> this document, the architectural entry point
├── Palette.md
│   -> palette model for the active insertable space
├── Express.md
│   -> guided authoring and normalization to canonical content
├── Observability.md
│   -> source-aligned execution observability contract for IDE tooling
├── Debugging.md
│   -> interactive debugging control behavior
├── Probes.md
│   -> local inspection probes for values and selected execution state
├── Watch.md
│   -> persistent centralized watch-based inspection model
└── Snippet.md
    -> image-backed snippet capture, transport, paste, and reuse workflows

The main upstream repository families that the IDE layer depends on are:

Expression/
    -> canonical source representation

Language/
    -> normative execution semantics

Libraries/
    -> intrinsic standardized primitive vocabularies

Profiles/
    -> optional standardized capability families

IR/
    -> canonical execution-facing representation and downstream handoff boundaries

This navigation matters because a FROG IDE is not a self-contained owner of language truth. It is a tooling layer built on top of source, meaning, execution-facing derivation, and observable execution projection.

4. Scope of this Document

This document specifies the architectural responsibilities of a FROG IDE.

It defines:

the role of the IDE shell,
the role of diagram and front-panel editors,
the role of the IDE-managed editable Program Model,
the IDE-facing boundary between authoring and execution-facing integration,
the role of palette-driven authoring,
the architectural role of Express authoring,
the role of execution observability,
the role of interactive debugging,
the role of probes,
the role of watch-based inspection,
the role of snippet-based authoring transport.

This document does not define:

the canonical .frog source format in full,
the normative execution semantics of the language,
the complete intrinsic primitive catalogs,
the complete optional profile catalogs,
the full compiler architecture,
the full runtime architecture,
the full execution-oriented IR architecture.

What this document owns
- IDE-facing architecture
- editing model
- discoverability model
- observability integration
- debugging / probes / watch / snippets
- Express behavior as an IDE concern

What this document does not own
- canonical source structure
- language semantics
- primitive semantics
- profile capability semantics
- compiler / runtime internals
- IR ownership

5. Relation with Other Specifications

The FROG repository separates several normative concerns.

Expression/ defines the canonical source representation of a FROG program.
Language/ defines cross-cutting normative execution semantics.
Libraries/ defines intrinsic standardized primitive catalogs and primitive-local semantics.
Profiles/ defines optional standardized capability families and profile-owned capability contracts.
IR/ defines canonical execution-facing representation, derivation, construction, lowering, and backend contracts.
IDE/ defines authoring, discoverability, observability, debugging, inspection, snippet behavior, and IDE-facing insertion behavior.

Accordingly:

this document is IDE-facing,
it may reference source, language, intrinsic-library, profile-owned, IR-side, and implementation-supported extension concepts,
but it does not replace the specifications that own those concepts normatively.

Ownership summary

Canonical source identity          -> Expression/
Execution semantics               -> Language/
Intrinsic primitive-local meaning -> Libraries/
Optional capability meaning       -> Profiles/
Execution-facing representation   -> IR/
Tooling behavior and UX           -> IDE/

One construct, multiple layers

Example: widget interaction

Expression/  -> widget objects and source-facing interaction representation
Libraries/   -> frog.ui.* primitive contracts
Language/    -> cross-cutting execution semantics
IR/          -> canonical execution-facing representation after validation
IDE/         -> how the user inserts, edits, observes, and debugs it

6. Responsibility Boundaries

A conforming FROG IDE MUST preserve the architectural separation between:

authoring,
canonical source serialization,
cross-cutting execution semantics,
intrinsic primitive definitions,
optional profile-owned capability definitions,
execution-oriented processing,
runtime execution,
canonical execution-facing representation,
source-aligned observability,
interactive debugging and inspection.

In particular:

the IDE edits programs through an IDE-managed Program Model,
the canonical saved artifact remains the .frog source representation,
language meaning is not defined by the editor UI,
primitive meaning is not defined by palette placement,
profile support is not defined by authoring convenience alone,
debugging and inspection do not redefine execution semantics,
the IDE MUST NOT treat its own Program Model as though it were the normative Execution IR.

Boundary rule

Nice IDE view
     ->
canonical Program Model identity
     ->
canonical source identity
     ->
validated execution-facing content

Never:

nice IDE view
     ->
new hidden language construct

7. High-Level Architecture

The IDE architecture combines:

authoring surfaces,
an editable in-memory Program Model,
serialization and reload services,
execution-facing integration boundaries,
source-aligned observability intake,
debugging and inspection tools.

                                   FROG IDE
                 +--------------------------------------------------+
                 | Diagram + Front Panel UI + Probes + Watches      |
                 +--------------------------+-----------------------+
                                            |
                                            v
                                 FROG Program Model
                           (editable in-memory source model)
                                            |
                     +----------------------+----------------------+
                     |                                             |
                     | save / load                                 | execute / validate
                     v                                             v
           OPEN SOURCE LAYER                              Validation against
           FROG Expression                                +----------------------+
           (.frog, canonical source)                      | Expression/          |
                                                          | Language/            |
                                                          | Libraries/           |
                                                          | Profiles/            |
                                                          +----------+-----------+
                                                                     |
                                                                     v
                                                   OPEN EXECUTION LAYER
                                                   FROG Execution IR
                        (canonical execution-facing document, derived, inspectable,
                           source-attributed, execution-facing, not backend-private)
                                                                     |
                                                                     v
                                                     Identity / Mapping preservation
                                                                     |
                                                                     v
                                                    Lowering / backend-facing handoff
                                                                     |
                                                                     v
                                          Compiler(s) / Backend(s) / Runtime(s)
                                                                     |
                                                                     v
                                                       Target execution instance
                                                                     |
                                                                     v
                                           Source-aligned execution observability
                                          (mapped back to meaningful FROG objects)
                                               /                |                 \
                                              /                 |                  \
                                             v                  v                   v
                                       Debugging            Probes               Watches
                                  pause / resume /      local source-       persistent centralized
                                   break / step         attached view          inspection view

This architecture is conceptual. Different IDE implementations MAY distribute these responsibilities differently across modules or processes, but the responsibility boundaries SHOULD remain stable.

Authoring / execution split

Editors + Palette + Express
            |
            v
      Program Model
            |
            v
     canonical source
            |
            v
validation / preparation
            |
            v
execution-facing systems
            |
            v
observability back to the IDE
            |
            +-> debugging
            +-> probes
            \-> watches

8. Current Documents

The IDE layer is currently organized as follows:

IDE/
├── Readme.md
│   -> architectural entry point for the FROG IDE and Program Model
├── Palette.md
│   -> palette model for the active insertable space, including primitives,
│      structures, node insertions, annotations, guided entries,
│      conditional profile-defined entries, and third-party entries
├── Express.md
│   -> guided Express authoring model and normalization to canonical FROG content
├── Authoring provenance.md
│   -> IDE-side creation, verification, display, review, and preservation workflows for source-carried provenance
├── Observability.md
│   -> source-aligned live execution observability contract for IDE tooling
├── Debugging.md
│   -> interactive debugging behavior built on source-aligned observability
├── Probes.md
│   -> live local inspection probes for values and selected execution state
├── Watch.md
│   -> persistent centralized watch-based inspection model
└── Snippet.md
    -> image-backed snippet capture, transport, paste, and reuse workflows

Together, these documents define the current IDE-facing baseline for authoring, discoverability, source-carried provenance display and review, source-aligned execution visibility, interactive debugging, inspection, and portable authoring-fragment transport.

9. Main Components

A FROG IDE typically includes the following architectural components:

an IDE shell,
a diagram editor,
a front-panel editor,
a FROG Program Model,
source serialization and reload services,
validation and execution-preparation integration,
palette services,
Express authoring services,
authoring provenance services,
execution observability integration,
debugging services,
probe services,
watch services,
snippet services.

Main component grouping

Authoring components
- IDE shell
- diagram editor
- front panel editor
- palette
- Express services
- authoring provenance services
- snippets

Model components
- Program Model
- serialization / reload
- consistency management

Execution-facing integration
- validation gateway
- execution preparation bridge
- observability intake
- debugging / probe / watch consumers

10. IDE Shell

The IDE shell is the host application responsible for coordinating the development environment. It manages the surrounding application experience rather than the language itself.

Typical responsibilities include:

window and layout management,
menus, toolbars, and command routing,
project and file navigation,
document lifecycle management,
plugin and extension loading,
integration between editors, palette tools, Express configuration tools, validation services, execution tooling, debugging tools, probe tools, watch tools, and snippet tools.

IDE shell owns orchestration, not language meaning.

Good examples:
- command routing
- dockable panes
- project browser
- view coordination
- execution-tool pane coordination

Not owned by the shell:
- canonical source semantics
- primitive semantics
- profile semantics
- IR semantics

11. Diagram Editor

The diagram editor is the graphical programming environment where users construct executable FROG graphs. It is an authoring surface for the FROG Program Model.

The diagram editor manipulates concepts such as:

primitive nodes,
structure nodes,
sub-FROG invocation nodes,
interface boundary nodes,
widget_value nodes,
widget_reference nodes,
wires and typed ports,
annotations and layout information,
editor interaction state.

Key capabilities typically include:

smooth zoom and pan,
real-time node and wire manipulation,
incremental validation feedback,
large-graph navigation,
execution observability overlays,
debugging overlays and source-level pause localization,
probe placement and probe visualization,
watch creation and watch/source navigation workflows,
snippet capture, paste, image export, and drag-and-drop insertion workflows,
Express insertion, reconfiguration, and detach/materialize workflows where supported.

12. Front Panel Editor

The front-panel editor is used to design the graphical interaction layer associated with a FROG program. It edits the widget tree declared in the front_panel section of the FROG Expression.

The front-panel editor is responsible for:

widget declaration,
widget composition and nesting,
layout and positioning,
styling and visual presentation,
design-time widget configuration.

The front panel is not:

the public logical interface of the FROG,
the executable graph of the FROG,
the place where ordinary value-flow bindings are defined.

Three related but different things

Public interface  -> reusable program boundary
Diagram           -> authoritative executable graph
Front panel       -> graphical interaction surface

Do not collapse them into one concept.

13. FROG Program Model

The FROG Program Model is the canonical editable in-memory representation maintained by the IDE. It is the authoritative form of the program during authoring.

It unifies the information required for editing and IDE-side consistency management, including:

metadata,
public interface definitions,
connector information,
diagram content,
structure regions and nested scopes,
front-panel widget trees,
icon and editor-related data,
cross-section consistency information,
authoring-side view state where such state is needed to preserve a stable editing experience without redefining canonical meaning.

When source provenance is enabled, the Program Model SHOULD keep enough stable source-object identity to create, verify, display, and update ide.provenance attestations without allowing those attestations to redefine canonical meaning.

Authoring ownership

IDE edits Program Model
        |
        v
Program Model preserves canonical source identity
        |
        v
Source serialization produces .frog Expression

What the Program Model is not

It is not:
- the raw .frog file
- the execution IR
- the runtime instance
- the normative language semantics

It is:
- the IDE's canonical editable model

14. Relation with FROG Expression

The canonical saved source artifact of a FROG program is the FROG Expression stored in a .frog file. That source format is defined in Expression/.

The IDE is expected to:

load canonical source into the Program Model,
edit the Program Model during authoring,
serialize the Program Model back into canonical source,
preserve source-level meaning and identity across those operations.

Round-trip invariant

load source
   -> build Program Model
   -> edit through IDE views
   -> serialize canonical source
   -> reload
   -> recover same canonical construct identity

15. Execution Integration Boundary

A FROG IDE MAY integrate validation, execution preparation, compiler services, runtime services, or equivalent execution-facing subsystems.

However, this document does not define those subsystems in full. It defines only the IDE-facing architectural boundary around them.

At minimum, an execution-capable IDE typically needs:

validation before live execution or build preparation,
a transition from editable authoring state to execution-prepared state,
a way to attach source identity to execution-observable objects,
a way to consume live execution observations for debugging and inspection.

Execution boundary rule

Program Model / source meaning
            |
            v
validated canonical content
            |
            v
execution-facing systems

Not required:
- editor aliases
- palette labels
- Express UI state
- presentation-only hints

16. Palette

The palette is the primary IDE mechanism for discovering and inserting elements from the active insertable space. That space may include intrinsic primitives, profile-defined primitives, structures, node insertions, annotations, guided entries, and implementation-supported third-party entries.

The palette belongs to the IDE layer because it is an authoring and discovery surface rather than a primitive catalog.

Palette responsibility

Palette answers:
- how users find things
- how users browse things
- how users insert things

Palette does not answer:
- what a primitive means
- what a profile means
- what execution semantics are
- what IR semantics are

17. Express Authoring

Express authoring is the IDE-layer capability that allows a user to insert or edit common programming constructs through a guided configuration experience rather than through raw low-level assembly alone. It exists to improve discoverability, speed of use, and usability for common tasks without creating a separate language.

An Express entry is therefore:

assistant-driven,
instance-local,
task-oriented,
normalizable to canonical FROG content.

Express lifecycle

choose entry
    ->
configure
    ->
resolve to canonical target
    ->
serialize canonical content
    ->
reopen / reconfigure if desired
    ->
detach safely if desired

18. Execution Observability

Execution observability is the architectural layer that exposes a source-aligned live view of a running FROG instance to the IDE. It allows runtime activity to be projected back onto diagram and front-panel-related source objects without redefining the execution semantics of the language.

Conceptually, execution observability sits between live execution and IDE inspection/debugging features. It is responsible for making runtime activity visible in terms such as:

node activation,
edge-level value availability,
structure entry and region selection,
loop iteration progression,
local-memory state activity,
pause-consistent execution snapshots.

Live execution
      |
      v
observable source-aligned events
      |
      +-> debugging
      +-> probes
      +-> watches
      \-> visual execution overlays

The detailed source-level contract for this layer belongs in IDE/Observability.md.

19. Debugging

Debugging is the interactive control layer built on top of live execution observability. It allows an IDE to pause, resume, inspect, and guide execution in a source-level way.

Canonical debugging capabilities include:

execution highlighting,
manual pause and resume,
breakpoints,
single-step controls,
fault-directed source localization.

Not this:
line 41 -> line 42 -> line 43

But this:
observable graph activity
      ->
pause / break / step over source-meaningful events

The detailed source-level behavior of these controls belongs in IDE/Debugging.md.

20. Probes

Probes are source-aligned live inspection tools built on top of execution observability and used together with debugging. They allow an IDE to observe values or source-level execution state associated with graph-meaningful objects.

Probes belong to the inspection layer. They do not alter program semantics, and they are not part of the canonical .frog source representation. They remain compatible with debugging, but they are not owned by debugger control.

Probe mental model

edge / port / state object
          |
          v
temporary local live inspection

The detailed source-level behavior of probes belongs in IDE/Probes.md.

21. Watch

Watch is the persistent inspection layer of the IDE. Where probes are attached directly to visible source locations, watch entries are persistent inspection objects gathered in a centralized view.

A watch-capable IDE typically supports:

persistent observation across pauses and resumes,
multiple simultaneous watched objects,
navigation from watch entry to source object,
inspection of values, state, and selected source-aligned execution objects,
combination with debugging workflows.

Probe vs Watch

Probe -> local, attached, immediate
Watch -> centralized, persistent, managed list

The detailed watch model belongs in IDE/Watch.md.

22. Snippets

Snippets are portable IDE artifacts used to capture, transport, preview, and reinsert reusable authoring fragments. They support workflows such as:

copy and paste of reusable diagram fragments,
drag-and-drop insertion into a target editor,
sharing small reusable authoring patterns,
transporting a graph fragment with its visual layout and related metadata,
front-panel or composite authoring reuse,
visual sharing of reusable fragments outside the IDE.

In FROG, a standalone snippet artifact is intended to be image-backed. It is visible as a normal image outside the IDE and decodable as structured payload inside a conforming IDE.

Snippet model

visible image
      +
embedded structured payload
      =
portable authoring fragment

The detailed snippet transport and insertion model belongs in IDE/Snippet.md.

23. Design Principles

Clear separation of source, authoring model, and execution-facing systems
Clear separation of Program Model and canonical Execution IR
Language independence from IDE implementation
Open serialized program representation
Instant editing feedback
Incremental validation
Hardware-agnostic execution
Cross-platform tooling
Scalable graphical editing for large programs
Explicit separation between interface, front panel, and diagram
Source-aligned execution observability
Dataflow-native debugging semantics
Non-intrusive live inspection through probes
Persistent centralized inspection through watch views
Portable authoring-fragment transport through snippets
Image-backed reusable snippet workflows for drag-and-drop authoring reuse
Authoring convenience without semantic drift
Preservation of canonical identity across aliases, views, guided flows, and contextual insertion workflows
Express authoring as an IDE convenience layer rather than a separate language
Deterministic normalization from guided authoring to canonical source content
Optional IDE recoverability metadata without executable authority
Optional authoring provenance metadata without executable authority
Visible distinction between unknown, AI-generated, human-direct, human-reviewed, stale, invalid, and untrusted provenance states where provenance-aware tooling is enabled
Clear distinction between intrinsic capability discovery, optional profile discovery, and third-party discovery

24. Repository Direction

At the current repository stage, IDE/ is the home for IDE-facing specifications such as:

overall IDE architecture,
palette behavior,
Express authoring behavior,
execution observability,
debugging,
probes,
watches,
snippets.

The long-term repository architecture SHOULD preserve a stable separation between:

Expression/ for canonical source representation,
Language/ for normative execution semantics,
Libraries/ for intrinsic standardized primitive catalogs,
Profiles/ for optional standardized capability families,
IR/ for canonical execution-facing representation and downstream handoff boundaries,
IDE/ for authoring, discoverability, guided authoring behavior, observability, debugging, and inspection.

Long-term direction

Keep IDE/ focused on:
- authoring
- discoverability
- observability
- debugging
- inspection
- snippet transport
- guided UX layers

Do not drift IDE/ into:
- source ownership
- language semantics
- primitive semantics
- profile semantics
- IR ownership
- runtime specification

25. Summary

A FROG IDE is not just a diagram editor. It is a layered authoring and inspection environment centered on:

a canonical editable Program Model,
a canonical source representation defined outside the IDE layer,
palette-driven and Express-capable authoring workflows,
a source-aligned execution observability layer,
dataflow-native debugging and inspection tools,
portable snippet-based authoring reuse workflows.

In that architecture:

editing operates on the Program Model,
storage operates through the canonical FROG Expression,
execution-facing systems remain separate from IDE ownership,
runtime activity becomes visible through execution observability,
debugging, probes, and watches consume that observable view as parallel IDE-side tools,
snippets provide portable, image-backed authoring-fragment reuse workflows,
Express authoring provides guided insertion and reconfiguration without creating a separate language layer,
the Program Model remains distinct from canonical Execution IR and from runtime-private realization.

This architecture allows FROG to remain an open graphical language while supporting serious IDE implementations without confusing source ownership, language ownership, intrinsic primitive ownership, optional profile ownership, execution-facing systems, and IDE-facing tooling.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FROG IDE Architecture

Contents

1. Overview

2. Document Role

3. Repository Navigation

4. Scope of this Document

5. Relation with Other Specifications

6. Responsibility Boundaries

7. High-Level Architecture

8. Current Documents

9. Main Components

10. IDE Shell

11. Diagram Editor

12. Front Panel Editor

13. FROG Program Model

14. Relation with FROG Expression

15. Execution Integration Boundary

16. Palette

17. Express Authoring

18. Execution Observability

19. Debugging

20. Probes

21. Watch

22. Snippets

23. Design Principles

24. Repository Direction

25. Summary

FilesExpand file tree

Readme.md

Latest commit

History

Readme.md

File metadata and controls

FROG IDE Architecture

Contents

1. Overview

2. Document Role

3. Repository Navigation

4. Scope of this Document

5. Relation with Other Specifications

6. Responsibility Boundaries

7. High-Level Architecture

8. Current Documents

9. Main Components

10. IDE Shell

11. Diagram Editor

12. Front Panel Editor

13. FROG Program Model

14. Relation with FROG Expression

15. Execution Integration Boundary

16. Palette

17. Express Authoring

18. Execution Observability

19. Debugging

20. Probes

21. Watch

22. Snippets

23. Design Principles

24. Repository Direction

25. Summary