Skip to main content

System

The system construct is the entry point of every WORDS specification. It names the application, gives it a human-readable description and declares the modules from which the application is composed. There is exactly one system in a WORDS project.

Purpose​

system does not define module behavior, states, transitions, or domain data. Its role is organisational: it breaks the application into named modules, each responsible for a distinct functional area, so that any change — whether to a specification or an implementation — can live within the right boundary.

An engineer reading a system block can understand the shape of the entire application — which functional areas it contains, how many there are, and what they are called — without reading anything else.

Runtime Access​

Beyond naming and listing modules, system exposes runtime access to them — such as system.RoutingModule — and provides a built-in interface for persisting contexts across module boundaries. The interface exposes three methods: getContext, which retrieves a stored context by name, setContext, which stores one, and dropContext, which removes the stored context entirely. These are the only runtime capabilities that live at the system level. Everything else belongs to the modules themselves.

The system. prefix marks a call resolved through the running system registry, especially built-in system operations and cross-module runtime calls. A state using an adapter within its own module, or a screen referencing a view from another module, is declaring a design-time dependency and uses the qualified name alone — ModuleName.ComponentName. A call that must be dispatched through the running system — such as system.setContext, system.RoutingModule.dispatch, or an interface component loading data from another module's adapter — uses the system. prefix to signal registry-based resolution.

Runtime calls use parenthesized named arguments:

system.getContext (
    name is AuthenticatedSession
)

system.setContext (
    name is AuthenticatedSession,
    value is context
)

system.RoutingModule.dispatch (
    path is "/home"
)

In these examples, the dot resolves the runtime path. The parenthesized argument block invokes it.

Syntax​

SystemName.wds
system SystemName "A description of the application" (
    modules (
        ModuleOne
        ModuleTwo
        ModuleThree
    )

    interface (
        getContext name(string) returns(context) "Retrieves the value of a stored context by its name"
        setContext name(string) value(context) "Stores a context by name"
        dropContext name(string) "Clears a context identified by name"
    )
)

The system keyword is followed by the application's name, an optional description in quotes and a body in parentheses. Inside the body, the modules block lists every module in the application by name, one per line. The interface describes what the system exposes to every module.

The description is optional but recommended — it is the first thing any reader, human or model, will see when opening the specification.

File Location​

The system construct lives in a single file at the root of the WORDS project:

/my-project/SystemName.wds

This file should be named after the system name followed by the .wds extension and needs to sit at the root of the project's directory. Every other construct in the project belongs to a module and is organised within its module's directory.

Examples​

A minimal single-module application:

NotesApp.wds
system NotesApp "A personal note-taking application" (
    modules (
        NotesModule
    )

    interface (
        getContext name(string) returns(context) "Retrieves the value of a stored context by its name"
        setContext name(string) value(context) "Stores a context by name"
        dropContext name(string) "Clears a context identified by name"
    )
)

A mid-size product covering authentication, session management, routing and catalogue functionality:

ShopFront.wds
system ShopFront "An e-commerce storefront" (
    modules (
        RoutingModule
        AuthModule
        SessionModule
        CatalogueModule
        CartModule
        CheckoutModule
    )

    interface (
        getContext name(string) returns(context) "Retrieves the value of a stored context by its name"
        setContext name(string) value(context) "Stores a context by name"
        dropContext name(string) "Clears a context identified by name"
    )
)

A back-office tool focused on data processing:

ReportingService.wds
system ReportingService "Internal data reporting and export service" (
    modules (
        IngestionModule
        TransformModule
        ExportModule
        SchedulerModule
    )

    interface (
        getContext name(string) returns(context) "Retrieves the value of a stored context by its name"
        setContext name(string) value(context) "Stores a context by name"
        dropContext name(string) "Clears a context identified by name"
    )
)

In each case, the system block communicates the scope of the application. The module names signal the functionalities involved. Nothing about how those functionalities behave needs to be understood here — that is the responsibility of each module individually.

Relationship to Other Constructs​

Every module listed in the modules block must have a corresponding module definition in the project root directory as the system construct does not define them and only declares that they exist.

The system file rarely needs to change. New behavior is added by creating or modifying modules. The system file is only updated when a module is added to or removed from the application entirely.