# Architecture

## Module Organization

The codebase is organized into self-contained modules in `src/`:

**Core Libraries (Lua + C):**

- `std/` - Standard library
   * filesystem (`std.fs`)
   * process (`std.ps`)
   * UTF-8 (`std.utf`)
   * text (`std.txt`)
   * tables (`std.tbl`)
   * conversions (`std.conv`)
   * MIME types (`std.mime`)
   * logging (`std.logger`)
- `term/` - Terminal I/O with Kitty keyboard & graphic protocols support, widgets, TSS (Terminal Style Sheets)
- `crypto/` - Cryptography via LITLS
- `lev/` - Async I/O runtime: epoll event loop, TCP/UDP sockets with TLS 1.3 via LITLS
- `mneme/` - Embedded key-value DB with FT and vector support
- `lem/` - LEM text editor
- `zlib/` - Deflate, zlib-wrapped, and gzip compression, CRC-32/Adler-32 checksums via `miniz`
- `evdev/` - Linux input devices (joysticks/gamepads): device identity, per-axis calibration, raw event stream

**Pure Lua Libraries:**

- `shell/` - The Lilush Shell implementation (see Shell Architecture below)
- `git/` - Pure-Lua git repository reader (`git`: objects, refs, index), packfile generation (`git.pack`), shell prompt status (`git.prompt`)
- `argparser/` - Argument parsing
- `markdown/` - Markdown parser and renderers (static, streaming, HTML)
- `redis/` - Async Redis protocol client (requires `lev.run()` context)
- `dns/` - DNS client library (caching, CNAME following, failover, UDP/TCP/DoT transports)
- `testimony/` - Minimal testing framework for Lilush
- `theme/` - Central TSS-based styling for shell, markdown, and agent
- `lilpack/` - LILPACK package system (MNEME-backed module loading)
- `http/` - HTTP client and server, SSE streaming, URL parsing, form-data encoding/parsing, read-only git smart-HTTP serving (`http.git`)

**C-only Libraries:**

- `cjson/` - Fast JSON encoding/decoding
- `wireguard/` - WireGuard client bindings
- `inotify/` - File system event monitoring
- `litls/` - Lilush TLS stack

### Shell Architecture

Consult [SHELL.md](SHELL.md) for the Lilush Shell (`src/shell/`) detailed overview.
The shell has three built-in modes: `shell` (F1), `lua` REPL (F2), and
`wiki` viewer (F3). The wiki mode opens self-describing MNEME databases
for browsing, searching, and viewing content — see [WIKIDB.md](WIKIDB.md).

### Binary Preloading System

Lilush embeds all modules in the binary:

1. **Lua modules** - Compiled to bytecode, embedded as C char arrays
2. **C modules** - Statically linked, registered via `luaL_Reg`
3. **Preloading** - Both registered in `package.preload` before Lua execution

The `c_tmpl` template generates:

- `mod_lua__t lua_preload[]` - Array of Lua bytecode modules
- `luaL_Reg c_preload[]` - Array of C module loaders
- `preload_modules(L)` - Populates `package.preload`

### Module Registration

#### Adding a new Lua module:

1. Create files in `src/yourmodule/*.lua`
2. Add module to `buildgen/modinfo.lua` luamods section
3. Add to whichever app configs need it (e.g. `buildgen/apps/lilush.lua`, `buildgen/apps/lilu.lua`) luamods array

#### Adding a new C module:

1. Create source in `src/yourmodule/*.c` with `luaopen_*` function
2. Create `src/yourmodule/Makefile`
3. Add to `buildgen/modinfo.lua` c_libs section
4. Add to whichever app configs need it (e.g. `buildgen/apps/lilush.lua`, `buildgen/apps/lilu.lua`) c_libs array

### File Paths and Package Loading

Lilush uses the LILPACK system for package loading. On startup,
`lilpack.init()` strips all default Lua searchers except the preload
searcher, then installs two custom searchers:

1. **LILPACK searcher** - Loads modules from MNEME-backed `.lilpack`
   databases in `~/.local/share/lilush/packages/`
2. **Script-local searcher** - Tries `./module.lua` and `./module/init.lua`
   relative to CWD

After initialization, `package.path` is set to an empty string.
See [LILPACK.md](LILPACK.md) for the full package system specification.