# violetsoul/xoscript architecture

> Architecture diagram of the GitHub repository violetsoul/xoscript, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/violetsoul/xoscript
- Repository: https://github.com/violetsoul/xoscript

## Overview

XOScript is a small server-side scripting language and interpreter. The main workflow is a developer running a `.xo` program through the interpreter; its documented server workflow uses the optional Server plugin with a CGI web server. The graph preserves the language front end, runtime, localization, and major server capabilities, plus the separate `xotr` translation tool. Source excerpts are partial: server initialization and imports are visible, but the interpreter’s complete execution path and several plugin implementations were not sampled.

Main entry points: [`src/plugins/server/server.c`](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/server.c) (Server Plugin), [`src/xo.c`](https://github.com/violetsoul/xoscript/blob/master/src/xo.c) (Interpreter), [`src/parser.c`](https://github.com/violetsoul/xoscript/blob/master/src/parser.c) (Parser), [`src/walker.c`](https://github.com/violetsoul/xoscript/blob/master/src/walker.c) (Program Walker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Front End"]
  node_interpreter["Interpreter<br/>[xo.c]"]
  node_lexer["Lexer<br/>[lexer.c]"]
  node_parser["Parser<br/>[parser.c]"]
  node_walker["Program Walker<br/>[walker.c]"]
end

subgraph group_runtime["Interpreter Runtime"]
  node_objects["Objects and Messages<br/>[base.c]"]
  node_world["World and Context<br/>[world.c]"]
  node_system["System Features<br/>[system.c]"]
  node_collections["Collections<br/>[collections.c]"]
  node_files["File Operations<br/>[file.c]"]
  node_runtime_memory["Memory Management<br/>[memory.c]"]
  node_language_terms["Language Vocabulary<br/>[dictionary.h]"]
  node_language_messages["Runtime Messages<br/>[msg.h]"]
end

subgraph group_server["Server Plugin"]
  node_server_plugin["Server Plugin<br/>[server.c]"]
  node_cgi["CGI Parsing<br/>[ccgi.c]"]
  node_http["HTTP Requests<br/>[http.h]"]
  node_json["JSON Support<br/>[json.c]"]
  node_jsmn["JSON Tokenizer<br/>[jsmn.c]"]
  node_vault["Vault<br/>[vault.c]"]
  node_mariadb["MariaDB<br/>[mariadb.c]"]
  node_crypto["Cryptography<br/>[monocypher.c]"]
  node_network["Network Support<br/>[net.c]"]
  node_ffi["Foreign Calls<br/>[fficonnect.c]"]
end

subgraph group_tools["Language Tools"]
  node_translator["XO Translator<br/>[xotr.c]"]
end

node_developer(("Developer"))
node_script["XO Program"]

node_developer -->|"writes"| node_script
node_developer -->|"runs"| node_interpreter
node_script -->|"provides program"| node_interpreter
node_interpreter -.->|"loads input"| node_lexer
node_parser -->|"reads tokens"| node_lexer
node_interpreter -.->|"parses program"| node_parser
node_parser -.->|"builds AST for"| node_walker
node_walker -.->|"evaluates messages"| node_objects
node_interpreter -.->|"initializes runtime"| node_world
node_interpreter -.->|"exposes features"| node_system
node_server_plugin -->|"initializes"| node_http
node_server_plugin -->|"initializes"| node_json
node_server_plugin -->|"initializes"| node_vault
node_server_plugin -->|"initializes"| node_mariadb
node_server_plugin -.->|"initializes optionally"| node_ffi
node_server_plugin -.->|"may use"| node_network
node_http -->|"uses CGI definitions"| node_cgi
node_json -->|"uses tokenizer"| node_jsmn
node_developer -->|"translates program"| node_translator

click node_interpreter "https://github.com/violetsoul/xoscript/blob/master/src/xo.c"
click node_lexer "https://github.com/violetsoul/xoscript/blob/master/src/lexer.c"
click node_parser "https://github.com/violetsoul/xoscript/blob/master/src/parser.c"
click node_walker "https://github.com/violetsoul/xoscript/blob/master/src/walker.c"
click node_objects "https://github.com/violetsoul/xoscript/blob/master/src/base.c"
click node_world "https://github.com/violetsoul/xoscript/blob/master/src/world.c"
click node_system "https://github.com/violetsoul/xoscript/blob/master/src/system.c"
click node_collections "https://github.com/violetsoul/xoscript/blob/master/src/collections.c"
click node_files "https://github.com/violetsoul/xoscript/blob/master/src/file.c"
click node_runtime_memory "https://github.com/violetsoul/xoscript/blob/master/src/memory.c"
click node_language_terms "https://github.com/violetsoul/xoscript/blob/master/src/i18n/en/dictionary.h"
click node_language_messages "https://github.com/violetsoul/xoscript/blob/master/src/i18n/en/msg.h"
click node_server_plugin "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/server.c"
click node_cgi "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/ccgi/ccgi.c"
click node_http "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/http.h"
click node_json "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/json.c"
click node_jsmn "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/jsmn/jsmn.c"
click node_vault "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/vault.c"
click node_mariadb "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/mariadb.c"
click node_crypto "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/monocypher/src/monocypher.c"
click node_network "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/net.c"
click node_ffi "https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/fficonnect.c"
click node_translator "https://github.com/violetsoul/xoscript/blob/master/misc/xotr/xotr.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_interpreter,node_lexer,node_parser,node_walker toneBlue
class node_objects,node_world,node_system,node_collections,node_files,node_runtime_memory,node_language_terms,node_language_messages toneAmber
class node_server_plugin,node_cgi,node_http,node_json,node_jsmn,node_vault,node_mariadb,node_crypto,node_network,node_ffi toneMint
class node_translator toneRose
class node_developer,node_script toneIndigo
```

## Components

### Language Front End

- [Interpreter](https://github.com/violetsoul/xoscript/blob/master/src/xo.c): `src/xo.c`
- [Lexer](https://github.com/violetsoul/xoscript/blob/master/src/lexer.c): `src/lexer.c`
- [Parser](https://github.com/violetsoul/xoscript/blob/master/src/parser.c): `src/parser.c`
- [Program Walker](https://github.com/violetsoul/xoscript/blob/master/src/walker.c): `src/walker.c`

### Interpreter Runtime

- [Objects and Messages](https://github.com/violetsoul/xoscript/blob/master/src/base.c): `src/base.c`
- [World and Context](https://github.com/violetsoul/xoscript/blob/master/src/world.c): `src/world.c`
- [System Features](https://github.com/violetsoul/xoscript/blob/master/src/system.c): `src/system.c`
- [Collections](https://github.com/violetsoul/xoscript/blob/master/src/collections.c): `src/collections.c`
- [File Operations](https://github.com/violetsoul/xoscript/blob/master/src/file.c): `src/file.c`
- [Memory Management](https://github.com/violetsoul/xoscript/blob/master/src/memory.c): `src/memory.c`
- [Language Vocabulary](https://github.com/violetsoul/xoscript/blob/master/src/i18n/en/dictionary.h): `src/i18n/en/dictionary.h`
- [Runtime Messages](https://github.com/violetsoul/xoscript/blob/master/src/i18n/en/msg.h): `src/i18n/en/msg.h`

### Server Plugin

- [Server Plugin](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/server.c): `src/plugins/server/server.c`
- [CGI Parsing](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/ccgi/ccgi.c): `src/plugins/server/ccgi/ccgi.c`
- [HTTP Requests](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/http.h): `src/plugins/server/http.h`
- [JSON Support](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/json.c): `src/plugins/server/json.c`
- [JSON Tokenizer](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/jsmn/jsmn.c): `src/plugins/server/jsmn/jsmn.c`
- [Vault](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/vault.c): `src/plugins/server/vault.c`
- [MariaDB](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/mariadb.c): `src/plugins/server/mariadb.c`
- [Cryptography](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/monocypher/src/monocypher.c): `src/plugins/server/monocypher/src/monocypher.c`
- [Network Support](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/net.c): `src/plugins/server/net.c`
- [Foreign Calls](https://github.com/violetsoul/xoscript/blob/master/src/plugins/server/fficonnect.c): `src/plugins/server/fficonnect.c`

### Language Tools

- [XO Translator](https://github.com/violetsoul/xoscript/blob/master/misc/xotr/xotr.c): `misc/xotr/xotr.c`

### Other components

- **Developer**
- **XO Program**

## Connections

- Developer → XO Program: writes
- Developer → Interpreter: runs
- XO Program → Interpreter: provides program
- Interpreter → Lexer: loads input
- Parser → Lexer: reads tokens (evidence: `src/parser.c`)
- Interpreter → Parser: parses program
- Parser → Program Walker: builds AST for
- Program Walker → Objects and Messages: evaluates messages
- Interpreter → World and Context: initializes runtime
- Interpreter → System Features: exposes features
- Server Plugin → HTTP Requests: initializes (evidence: `src/plugins/server/server.c`)
- Server Plugin → JSON Support: initializes (evidence: `src/plugins/server/server.c`)
- Server Plugin → Vault: initializes (evidence: `src/plugins/server/server.c`)
- Server Plugin → MariaDB: initializes (evidence: `src/plugins/server/server.c`)
- Server Plugin → Foreign Calls: initializes optionally (evidence: `src/plugins/server/server.c`)
- Server Plugin → Network Support: may use
- HTTP Requests → CGI Parsing: uses CGI definitions (evidence: `src/plugins/server/http.h`)
- JSON Support → JSON Tokenizer: uses tokenizer
- Developer → XO Translator: translates program (evidence: `misc/xotr/xotr.c`)
