# nijakow/lmud architecture

> Architecture diagram of the GitHub repository nijakow/lmud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nijakow/lmud
- Repository: https://github.com/nijakow/lmud

## Overview

##### Project Type and Purpose
- LMud is a multi-user dungeon (MUD) engine and a Common Lisp dialect implementation that serves as a programming language and driver for building MUDs and similar networked applications.
- The project delivers a hybrid system built from both high-level Lisp source code (in the src/lisp directory) and lower-level core engine components written in C (in the src/lmud directory). It integrates a custom Lisp engine with networking, I/O, and user management to support interactive multi-user environments.

##### Analyzing the File Structure
- The top-level directories include:
- docs: Contains documentation files (e.g., Doxyfile for Doxygen configuration).
- src: Under which there are two main subdirectories:
▪ src/lisp: Contains the Lisp engine components. Further broken into:
- engine: Game logic, shell commands (e.g., shell.lisp, game.lisp), world and objects definitions.
- kernel: Core runtime, I/O (readline, streams, telnet, VT100), modules (REPL, sourcer), and utility functions.
- web: Contains the webserver module.
- misc: Contains test and other auxiliary files.
▪ src/lmud: Contains the C code for the LMud core including:
- Makefile and configuration headers.
- Files for integrating Lisp (glue, compiler, gc, etc.).
- Subsystems for networking (net/), system functions (console, logging, user management) and utilities.
- The structure indicates a clear separation between the Lisp-level interpreter/engine and the underlying C-based runtime that handles networking, I/O, and system integration.

##### Key Aspects

a. Main Components:
- Lisp Engine:
- Engine Module: Game logic, shell commands, world and objects.
- Kernel Module: I/O (readline, streams, telnet, VT100), modules for the REPL, and code sourcing.
- Web Module: A dedicated webserver for possibly handling web-based interactions.
- Miscellaneous & Prelude: Supporting tests and initial bootstrapping code.
- LMud Core (C-based):
- Main Execution: Main entry points (lmud.c, main.c) and configuration.
- Lisp Integration: Files under lmud/lisp for the runtime, builtins, compiler, memory management, and garbage collection.
- Network Subsystem: Management of connections, selectors, servers – handling multi-user connectivity.
- System Subsystem: Console handling, logging, log levels, and user management.
- Utility Libraries: For network utilities, memory management (ring buffer, string builder), and handling UTF-8 and vt100 protocols.
- Documentation: Managed by the docs folder (e.g., Doxygen settings).

b. Relationships and Interactions:
- The LMud core (C implementation) acts as the framework that initializes and coordinates system functions including network connectivity and system-level I/O.
- The embedded Lisp engine (and its modules) provides the domain-specific language and scripting capabilities that allow dynamic creation and control of MUD elements such as game logic, world management, and command processing.
- There is a clear interface or "glue" (e.g., src/lmud/glue.c/h files) that connects the Lisp code with the C runtime, enabling the evaluation of Lisp scripts to drive game behavior.
- The network subsystem is responsible for accepting connections from clients (via telnet or other supported protocols) and passing user commands to the Lisp engine and core game logic.
- Utility modules (in both C and Lisp parts) provide supporting services such as asynchronous I/O, memory management, logging, and terminal handling.

c. Architectural Patterns and Design Principles:
- Layered Architecture: Separation between the high-level scripting (Lisp engine) and low-level system services (C LMud core).
- Modularity: Modules are organized into distinct directories and components (e.g., I/O, networking, logging) with clear responsibilities.
- Integration via Glue Code: Bridging between languages (Lisp and C) through dedicated integration files.
- Use of a Build System: The Makefile indicates a compiled component integrated into the overall system, following standard build practices on POSIX environments.

d. Relevant Technologies and Frameworks:
- Common Lisp: Custom Lisp interpreter and language runtime.
- C Language: Underlying engine implementation including memory management, network handling, and system integration.
- GNU Make: Build system based on provided Makefiles.
- POSIX Environment: Assumed runtime system as per the README for building and running LMud.
- Telnet, VT100: Supported protocols for client connections and terminal interface.

##### Final Advice
- Keep consistency in labeling so that each component from the file structure is clearly mapped. This aids in troubleshooting and future enhancements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        TELNET["Telnet Clients"]:::external
        WEBCLIENTS["Web Clients"]:::external
    end

    %% LMud Core (C-based)
    subgraph "LMud Core (C-based)"
        CORE["Main Execution & Config"]:::cstyle
        GLUE["Lisp Integration / Glue Code"]:::cstyle
        COMPILER["Compiler & Bytecode"]:::cstyle
        GC["Garbage Collector"]:::cstyle
        NET["Network Subsystem"]:::cstyle
        CONSOLE["Console"]:::cstyle
        LOG["Logging"]:::cstyle
        USERMGMT["User Management"]:::cstyle
        UTIL["Utility Libraries"]:::cstyle
    end

    %% Lisp Engine
    subgraph "Lisp Engine"
        ENGINE["Engine (Game Logic & Scripting)"]:::lispstyle
        SHELL["Shell Commands"]:::lispstyle
        WORLD["World & Objects Management"]:::lispstyle
        KERNEL["Kernel Module (I/O,REPL,Utilities)"]:::lispstyle
        WEBMODULE["Web Module"]:::lispstyle
        MISC["Miscellaneous & Prelude"]:::lispstyle
    end

    %% Documentation
    subgraph "Documentation"
        DOCS["Documentation"]:::docstyle
    end

    %% Connections from External Clients to LMud Core Network Subsystem
    TELNET -->|"connects"| NET
    WEBCLIENTS -->|"connects"| NET

    %% LMud Core component interactions
    NET -->|"initializes"| CORE
    CORE -->|"invokes"| GLUE
    GLUE -->|"bridgesTo"| ENGINE
    GLUE -->|"loads"| COMPILER
    GLUE -->|"manages"| GC
    CORE -->|"calls"| CONSOLE
    CORE -->|"calls"| LOG
    CORE -->|"calls"| USERMGMT
    CORE -->|"utilizes"| UTIL

    %% Lisp Engine internal flow
    ENGINE -->|"delegatesTo"| SHELL
    ENGINE -->|"manages"| WORLD
    ENGINE -->|"interfacesWith"| KERNEL
    WEBCLIENTS -->|"serve"| WEBMODULE
    ENGINE -->|"bootstraps"| MISC
    ENGINE -->|"feedback"| NET

    %% Click Events for Lisp Engine Components
    click ENGINE "https://github.com/nijakow/lmud/tree/main/src/lisp/engine"
    click SHELL "https://github.com/nijakow/lmud/tree/main/src/lisp/engine/shell"
    click WORLD "https://github.com/nijakow/lmud/tree/main/src/lisp/engine/world"
    click KERNEL "https://github.com/nijakow/lmud/tree/main/src/lisp/kernel"
    click WEBMODULE "https://github.com/nijakow/lmud/blob/main/src/lisp/web/webserver.lisp"
    click MISC "https://github.com/nijakow/lmud/tree/main/src/lisp/misc"

    %% Click Events for LMud Core Components
    click CORE "https://github.com/nijakow/lmud/tree/main/src/lmud"
    click GLUE "https://github.com/nijakow/lmud/blob/main/src/lmud/glue.c"
    click COMPILER "https://github.com/nijakow/lmud/tree/main/src/lmud/lisp/compiler"
    click GC "https://github.com/nijakow/lmud/blob/main/src/lmud/lisp/gc.c"
    click NET "https://github.com/nijakow/lmud/tree/main/src/lmud/net"
    click CONSOLE "https://github.com/nijakow/lmud/tree/main/src/lmud/sys/console"
    click LOG "https://github.com/nijakow/lmud/tree/main/src/lmud/sys/log"
    click USERMGMT "https://github.com/nijakow/lmud/tree/main/src/lmud/sys/user"
    click UTIL "https://github.com/nijakow/lmud/tree/main/src/lmud/util"

    %% Click Event for Documentation
    click DOCS "https://github.com/nijakow/lmud/tree/main/docs/Doxyfile"

    %% Styles
    classDef cstyle fill:#ffeeaa,stroke:#333,stroke-width:2px;
    classDef lispstyle fill:#aaffaa,stroke:#333,stroke-width:2px;
    classDef external fill:#aaaaff,stroke:#333,stroke-width:2px;
    classDef docstyle fill:#ffddaa,stroke:#333,stroke-width:2px;
```
