System Architecture

Relevant source files

• .github/workflows/gradle.yml
• README.md
• build.gradle
• docs/build.gradle
• gradle/wrapper/gradle-wrapper.jar
• gradle/wrapper/gradle-wrapper.properties
• gradlew
• gradlew.bat
• modules/canvasfx/build.gradle
• modules/canvasfx/src/main/java/com/annimon/ownlang/modules/canvasfx/canvasfx.java
• modules/main/build.gradle
• modules/server/build.gradle
• modules/socket/build.gradle
• modules/socket/src/main/java/com/annimon/ownlang/modules/socket/socket.java
• ownlang-core/build.gradle
• ownlang-desktop/build.gradle
• ownlang-parser/build.gradle
• ownlang-utils/build.gradle
• settings.gradle

Purpose and Scope

This document describes the high-level architecture of the OwnLang programming language system, focusing on the multi-project structure, component relationships, and module ecosystem. It covers the organization of code modules, build system configuration, and distribution mechanisms that enable OwnLang's extensible design.

For detailed information about the language processing pipeline from lexical analysis to execution, see Language Core. For specifics about individual modules and their APIs, see Module System. For build automation and packaging details, see Build and Distribution.

Multi-Project Architecture Overview

OwnLang follows a modular multi-project architecture built with Gradle, separating concerns across distinct components with clearly defined dependencies.

Project Structure Diagram

The architecture separates language infrastructure from application logic and extension modules. The ownlang-core project provides the fundamental value system and runtime components, while ownlang-parser builds upon it to add language processing capabilities. The ownlang-desktop project serves as the primary application entry point, integrating all components.

Sources: settings.gradle1-14 ownlang-desktop/build.gradle21-25 build.gradle1-34

Dependency Structure

The project dependencies follow a layered architecture where each layer builds upon the previous:

Layer	Projects	Dependencies	Purpose
Foundation	ownlang-core	Java standard library, org.json	Core value system, basic runtime
Language Processing	ownlang-parser	ownlang-core	Lexical analysis, parsing, AST
Development Tools	ownlang-utils	ownlang-parser, jline	REPL, CLI utilities, optimization
Application	ownlang-desktop	All core projects, modules:main	Main executable, CLI interface
Extensions	modules:*	ownlang-core (compileOnly)	Standard library, specialized modules
Documentation	docs	Multiple projects	Documentation generation

Sources: ownlang-core/build.gradle8-9 ownlang-parser/build.gradle9 ownlang-utils/build.gradle9-10 modules/main/build.gradle9

Core Language Components

Runtime Architecture Diagram

The core components establish the runtime environment and language processing pipeline. The Value system in ownlang-core provides the foundation for all data types, while the parser components handle source code transformation into executable representations.

Sources: ownlang-desktop/build.gradle10 ownlang-core/build.gradle19-35 ownlang-parser/build.gradle9 ownlang-utils/build.gradle9-10

Module System Architecture

Module Integration Pattern

Each module implements the Module interface, providing constants and functions that extend the language's capabilities. The modular design allows for optional inclusion of specialized functionality while maintaining a lightweight core.

Sources: modules/canvasfx/src/main/java/com/annimon/ownlang/modules/canvasfx/canvasfx.java48 modules/socket/src/main/java/com/annimon/ownlang/modules/socket/socket.java17

Module Build Configuration

The module build system uses a standardized configuration pattern:

Sources: modules/canvasfx/build.gradle15-16 modules/server/build.gradle9-13 modules/socket/build.gradle9-17 build.gradle1-18

Build and Distribution System

Gradle Multi-Project Configuration

The build system uses Gradle's multi-project capabilities with centralized version management and consistent build patterns across all subprojects.

Component	Configuration	Purpose
Root Project	Version catalog in ext.versions	Centralized dependency management
Shadow Plugin	Applied to ownlang-desktop, modules	Fat JAR creation for distribution
Java Plugin	All projects	Standard Java compilation
JavaFX Plugin	modules:canvasfx only	JavaFX module system integration
Application Plugin	ownlang-desktop only	Main class configuration

Sources: build.gradle1-34 ownlang-desktop/build.gradle1-5 modules/canvasfx/build.gradle1-5

Distribution and Execution Tasks

The build system provides various execution and distribution tasks:

Sources: ownlang-desktop/build.gradle35-71 docs/build.gradle19-45 README.md137-153

Component Interaction Patterns

Initialization and Module Loading

The system follows a bootstrapping pattern where the desktop application coordinates module loading and runtime initialization:

1. Main Entry Point: com.annimon.ownlang.Main serves as the application entry point
2. Module Registration: Modules are loaded and their constants() and functions() methods are called
3. Runtime Environment: The combined functionality becomes available to OwnLang programs
4. Execution Context: Programs can access all registered modules through use statements

The compileOnlyApi dependency pattern for modules ensures that the core runtime is provided by the main application, avoiding classpath conflicts while enabling modular development.

Sources: ownlang-desktop/build.gradle10-11 modules/main/build.gradle9 modules/canvasfx/build.gradle16

This architecture enables OwnLang to maintain a lightweight core while supporting extensive functionality through its module system, with a build system that supports both development workflows and distribution requirements.