add website with docs
This commit is contained in:
parent
870c20e745
commit
fcf1979a1d
12 changed files with 541 additions and 314 deletions
46
website/doc/glossary.org
Normal file
46
website/doc/glossary.org
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
#+title: Grimu-R glossary
|
||||
|
||||
* Weave
|
||||
Defines a collection of braids.
|
||||
Represented by files on disk.
|
||||
* Braid
|
||||
Has reactive inputs and outputs.
|
||||
Serves as an externally invocable entry point.
|
||||
Contains sigils and/or nested braid instances connected by strands.
|
||||
Can be distributed within a schism aspect.
|
||||
* Sigil
|
||||
Has reactive inputs and outputs.
|
||||
Atomic execution unit.
|
||||
Cannot be directly invoked by an aspect consumer.
|
||||
May have an inscription.
|
||||
Created from a scroll and executed in the grimoire environment.
|
||||
* Strand
|
||||
Connects a reactive input to a compatible reactive output.
|
||||
Can be cadence-decorated on both upstream and downstream ends.
|
||||
May be parameterized by a reactive input, consuming variable assignments for the cadence decoration.
|
||||
* Cadence
|
||||
Defines reactive behavior.
|
||||
May refer to variables defined by the reactive input.
|
||||
* Inscription
|
||||
Defines a script, a template or a configuration for a sigil to be executed with.
|
||||
May be defined statically in the weave or considered a reactive input.
|
||||
* Scroll
|
||||
Defines source code, its build dependencies and runtime environment.
|
||||
Provides a default sigil configuration.
|
||||
Provides default upstream/downstream cadence decorators for outputs/inputs respectively.
|
||||
Declares runtime compatibility (browser-only, non-browser, or universal).
|
||||
* Grimoire
|
||||
Complete environment required to execute (a part of) a weave.
|
||||
* Schism
|
||||
Splits the weave by grouping its braids into coherent collections of aspects.
|
||||
* Aspect
|
||||
Represents a collection of entire braids as an individual program.
|
||||
Uses rifts to communicate with other aspects within the same schism.
|
||||
* Rift
|
||||
Acts as a proxy for a braid instance that was separated into a different aspect.
|
||||
Enables strands to cross process and network boundaries.
|
||||
* Binding
|
||||
Provides a build strategy for a schism.
|
||||
Maps an aspect to a specific build recipe producing an executable or a container.
|
||||
* Loom
|
||||
Provisions tools for interactive or programmatic weaving and execution.
|
||||
35
website/doc/weaving_guide.org
Normal file
35
website/doc/weaving_guide.org
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
#+title: Grimu-R lifecycle guide
|
||||
|
||||
* Project initialization
|
||||
- create your flake
|
||||
- add Grimu-R base as input
|
||||
- define and enter a dev shell
|
||||
* Interactive weaving
|
||||
- open Loom editor in the browser
|
||||
- create a braid
|
||||
- add sigils to it from the scrolls palette
|
||||
- connect them with strands
|
||||
- edit sigil inscriptions
|
||||
- execute sigils by clicking on their buttons
|
||||
- adjust cadence decoration
|
||||
* Modular weaving
|
||||
- factor out braids
|
||||
- define your own scrolls
|
||||
- import external scrolls and weaves as flake inputs
|
||||
- export yours as flake outputs
|
||||
- call braids from other programs
|
||||
* Deployment pipeline
|
||||
- define a schism with aspects containing braids
|
||||
- define a binding
|
||||
- build executables / containers
|
||||
* User-side weaving (malleability)
|
||||
- add Loom to the binding definition
|
||||
- deploy the executable
|
||||
- open Loom editor in the browser
|
||||
- persist edits in the browser
|
||||
- rebase persisted edits on top of new versions released by devs
|
||||
* Testing and test automation
|
||||
- use Loom in the browser to run and inspect interactively
|
||||
- define test data right in the weave as static sigils
|
||||
- extract test data from the weave with Loom CLI
|
||||
- execute braids with test inputs with Loom CLI
|
||||
BIN
website/favicon.ico
Normal file
BIN
website/favicon.ico
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.7 KiB |
60
website/llms.txt
Normal file
60
website/llms.txt
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
# Grimu-R
|
||||
|
||||
**Grimu-R** is an open-source framework for mixed visual-textual dataflow scripting, combining interactive web-based visual editing with polyglot scripting runtime.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
**Weave**: A Git-friendly project representation containing the complete dataflow graph and layout
|
||||
**Braid**: Reusable modules/entry points that can be nested and serve as CLI subcommands or RPC methods
|
||||
**Sigil**: Basic building blocks - programs that act as data sources, sinks, or transformers
|
||||
**Scroll**: Defines runtime environment and default configuration for sigils (developed with Nix)
|
||||
**Inscription**: Dynamic scripts/templates stored in weaves, editable in the visual editor
|
||||
**Strand**: Connects reactive inputs/outputs with configurable cadence decorators
|
||||
**Schism/Aspect**: Splits weaves into deployable program collections
|
||||
**Loom**: Interactive weaving and execution tools
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Visual-textual editor**: Browser-based with immediate feedback and live code changes
|
||||
- **Reactive dataflow**: Granular configuration for push/pull, throttling, batching, backpressure
|
||||
- **Polyglot**: Real code blocks in familiar languages leveraging their ecosystems
|
||||
- **Nix-powered**: Reproducible builds and environments with minimal setup effort
|
||||
- **Malleable**: End users can inspect/modify dataflows using the same editor as developers
|
||||
- **Embeddable**: Builds to CLI tools, RPC servers, web apps, or containers
|
||||
- **Cross-language**: Structured data (JSON lines) connections between different runtimes
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Project setup**: Create Nix flake with Grimu-R base, enter dev shell
|
||||
2. **Interactive weaving**: Use browser-based Loom editor to create braids, add sigils, connect with strands
|
||||
3. **Modular development**: Factor out reusable braids, define custom scrolls, import/export as flake inputs/outputs
|
||||
4. **Testing**: Run interactively in browser, define test data as static sigils, extract/execute via Loom CLI
|
||||
5. **Deployment**: Define schisms with aspects, create bindings, build executables/containers
|
||||
|
||||
## Use Cases
|
||||
|
||||
- Rapid prototyping of data processing pipelines
|
||||
- Self-hosted workflow automation
|
||||
- Custom dashboards with complex logic
|
||||
- Internal tooling and automation scripts
|
||||
- Hacker-friendly, highly customizable applications
|
||||
|
||||
## Positioning
|
||||
|
||||
Takes the best from visual programming environments, script automation, and code notebooks while remaining developer-first. Avoids limitations of proprietary tools, brittleness of script bundles, and opacity of notebooks.
|
||||
|
||||
## Licensing
|
||||
|
||||
- **Platform components** (Loom tools, weave executors): AGPL v3
|
||||
- **Base scrolls and non-platform code**: MIT
|
||||
- AGPL applies to forks/extensions of platform code and SaaS deployments
|
||||
- Your weaves and applications using Grimu-R are not affected by AGPL terms
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- Development environment provisioned via Nix shell
|
||||
- Visual editor communicates over WebSocket
|
||||
- Changes stored in browser, exportable as files
|
||||
- Cross-language via structured data pipes (like Unix pipes with JSON)
|
||||
- Shared runtime dependencies managed by Nix
|
||||
- Malleability limited to client-side parts in client-server applications
|
||||
160
website/pandoc-template.html
Normal file
160
website/pandoc-template.html
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
<!DOCTYPE html>
|
||||
<html$if(lang)$ lang="$lang$"$endif$>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
$if(title)$
|
||||
<title>$title$</title>
|
||||
$endif$
|
||||
<style>
|
||||
html {
|
||||
display: flex;
|
||||
}
|
||||
|
||||
body {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
flex: 1;
|
||||
background-color: ivory;
|
||||
font-family: 'Courier New', Courier, monospace;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
width: 100%;
|
||||
border-bottom: 1px solid #ddd;
|
||||
min-height: 4em;
|
||||
}
|
||||
|
||||
header > div {
|
||||
flex: 1;
|
||||
}
|
||||
|
||||
header > h1 {
|
||||
text-align: center;
|
||||
flex: 1;
|
||||
margin: 10px;
|
||||
}
|
||||
|
||||
.nav {
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
gap: 2em;
|
||||
}
|
||||
|
||||
#content {
|
||||
display: flex;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.include-before {
|
||||
flex: 1;
|
||||
}
|
||||
|
||||
.content-body {
|
||||
flex: 2;
|
||||
}
|
||||
|
||||
@media (max-width: 1400px) {
|
||||
header > h1, .nav {
|
||||
flex: 10;
|
||||
}
|
||||
|
||||
.content-body {
|
||||
flex: 3;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 1000px) {
|
||||
header {
|
||||
flex-direction: column;
|
||||
padding-bottom: 10px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 700px) {
|
||||
.content-body {
|
||||
margin-left: 1em;
|
||||
margin-right: 1em;
|
||||
}
|
||||
|
||||
#content {
|
||||
flex-direction: column;
|
||||
}
|
||||
}
|
||||
|
||||
#content>div:nth-of-type(3) {
|
||||
flex: 1;
|
||||
}
|
||||
|
||||
section.level2 > h2 {
|
||||
border-left: 0.2em solid #3498db;
|
||||
padding-left: 0.5em;
|
||||
}
|
||||
|
||||
section.level3 > h3 {
|
||||
margin-left: 1em;
|
||||
}
|
||||
|
||||
section.level2 > p {
|
||||
margin-left: 1em;
|
||||
}
|
||||
|
||||
section.level3 > p {
|
||||
margin-left: 2em;
|
||||
}
|
||||
|
||||
section.level3 > ul {
|
||||
margin-left: 1em;
|
||||
}
|
||||
|
||||
section.level3 > ol {
|
||||
margin-left: 2em;
|
||||
}
|
||||
|
||||
li {
|
||||
padding-left: 0.1em;
|
||||
padding-bottom: 0.3em;
|
||||
}
|
||||
|
||||
a:link {
|
||||
color: #2E5EAA;
|
||||
text-decoration: none;
|
||||
}
|
||||
a:visited {
|
||||
color: #663399;
|
||||
}
|
||||
a:hover {
|
||||
color: #1a4480;
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<div></div>
|
||||
<h1 class='title'>$title$</h1>
|
||||
<div class="nav">
|
||||
<a href='/index.html'>home</a>
|
||||
<a href='/doc/glossary.html'>docs</a>
|
||||
<a href='/pitch.html'>pitch deck</a>
|
||||
<a href='/llms.txt'>llms</a>
|
||||
</div>
|
||||
</header>
|
||||
<div id="content">
|
||||
<div class="include-before">
|
||||
$for(include-before)$
|
||||
$include-before$
|
||||
$endfor$
|
||||
</div>
|
||||
<div class="content-body">
|
||||
$body$
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
53
website/pitch.org
Normal file
53
website/pitch.org
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
#+title: Grimu-R pitch deck
|
||||
* Key benefits
|
||||
** Rapid prototyping
|
||||
- Visual development and debugging
|
||||
- Executed directly on dev's machine
|
||||
- Immediate feedback
|
||||
** Flexibility
|
||||
- Not just workflows and dashboards -- anything
|
||||
- Embed existing software into a Grimu-R project
|
||||
- Embed a Grimu-R project itself into a larger flow
|
||||
- No inherent deployment limitations, execute anywhere
|
||||
** Clear evolution and hardening path
|
||||
- Start with a visual, interactive prototype
|
||||
- Decompose into components
|
||||
- Add builds and deployments
|
||||
- Call Grimu-R components from non Grimu-R components
|
||||
- Automate testing
|
||||
** Malleability
|
||||
- Power users have the same superpowers as developers
|
||||
- Can inspect, modify and extend available components in the visual editor
|
||||
- Highly adaptable, customizable internal tooling
|
||||
** No more "works on my machine"
|
||||
- Reproducible environments and builds with Nix
|
||||
- Every developer has the same tooling installed automatically
|
||||
** Knowledge transfer
|
||||
- Visual flow gives a clear overview and facilitates dev onboarding
|
||||
- Execution graphs are self-documenting, serving both as code and a diagram for it
|
||||
- Easier participation for less technical team members
|
||||
** Reusable modules
|
||||
- Base library components and integrations
|
||||
- An open ecosystem of third-party utilities, open-source and commercial
|
||||
- Develop and sell your own modules, or open source and get community support
|
||||
** Free as in freedom
|
||||
- The Grimu-R platform is open source, can be employed and extended freely
|
||||
- Works on your machines, not in some cloud you don't control
|
||||
* Caveats
|
||||
** Bespoke reactive dataflow graphs and tooling
|
||||
- Developers and power users need to get familiar with the mental model and tools
|
||||
- General, intuitive concepts but still unorthodox
|
||||
- Nifty and precise but alien jargon
|
||||
** Nix
|
||||
- Steep learning curve for developing your own components
|
||||
- Hated by a huge % of devs
|
||||
- There are limited ways to opt out
|
||||
** Performance overhead
|
||||
- Visual/textual scripts are fast to create, slow to execute
|
||||
- Compiled binaries can be used at the cost of some convenience
|
||||
- Deployable bundles are huge in volume
|
||||
- No single "blessed" way to scale (yet)
|
||||
** Copyleft licensing
|
||||
- The platform can be extended, and contributions are welcome
|
||||
- But your contributions must also be open source
|
||||
- Only applies to the platform -- not components and modules!
|
||||
Loading…
Add table
Add a link
Reference in a new issue