Malama — C++23 Core Internals & Architecture Specifications

System Architecture & Thread Boundaries

Decoupled multi-threaded design isolating asynchronous socket I/O from the native GTK rendering loop.

1. Asynchronous Networking & Coroutines

The network layer relies on Boost.Asio and Boost.Cobalt running inside a dedicated worker thread (std::jthread). Raw streaming LLM tokens are buffered and forwarded to the wxWidgets GUI thread via non-blocking wxQueueEvent dispatchers to keep UI framing strictly under 16ms.

2. Compile-Time JSON Reflection

Payload generation and response parsing bypass heavy runtime reflection trees by using the header-only glaze JSON library. The application parses lines in zero-copy chunks, providing high throughput while idling at less than 40 MB of RAM.

3. Factory-Routed Multimodal Ingestion

File attachments are staged in memory and processed by the ParserFactory. Uncompressed documents and images are read via poppler-cpp, libarchive, pugixml, libpng, and libjpeg before being converted to Base64 or UTF-8 prompt boundaries.

4. Relational Persistence & State Guarding

Conversations and metadata are stored in a local SQLite3 database. All queries use parameterized statements protected by scoped transaction guards across worker threads, preventing locks and corrupt state.

Source Repository Layout

Target-partitioned source tree separating pure domain business logic from GTK presentation components.

malama/
├── CMakeLists.txt                # Modern CMake root build file (generates compile_commands.json)
├── .clang-format                 # Code style specification (attached braces, right-aligned pointers)
├── .clang-tidy                   # Static analysis rules (enforces m_ prefixes and exception rules)
├── include/                      # Public C++ header files
│   ├── common/                   # Core types, constants, and domain data models (models.hpp, types.hpp)
│   ├── config/                   # Thread-safe configuration manager (config_manager.hpp)
│   ├── engine/                   # Business domain subsystems
│   │   ├── markdown/             # Custom Markdown-to-HTML parser (pipeline.hpp, syntax_registry.hpp)
│   │   └── storage/              # SQLite history manager and parser implementations
│   ├── network/                  # TCP streaming wrappers (ollama_client.hpp, stream_worker.hpp)
│   └── ui/                       # Native GTK/wxWidgets layout panels (main_frame.hpp, chat_panel.hpp)
├── libs/                         # Vendor header-only dependencies (glaze, spdlog, boost subsets)
├── src/                          # Implementation file source root (.cpp targets)
├── scripts/                      # Deployment shell runners (install.sh, uninstall.sh, build_appimage.sh)
└── tests/                        # Offline verification and unit testing suite
    ├── CMakeLists.txt            # Isolated CTest builder file
    ├── main_test.cpp             # Catch2 test suite entry point
    ├── unit/                     # Domain and parsing logic unit tests
    └── integration/              # Multi-module and containerized distro verification matrices

Core Class Reference & System Roles

Key C++ classes orchestrating application lifecycle, parsing pipelines, and UI interactions.

Class Name	Header & Namespace Path	Core Role & Operational Purpose
`MalamaApp`	`include/main.hpp` `malama::MalamaApp`	Application entry point inheriting from `wxApp`. Handles global initialization, spdlog setup, and initial window lifecycle.
`MainFrame`	`include/ui/main_frame.hpp` `malama::ui::MainFrame`	Top-level window controller managing menus, layout sizing, modal dialog execution, and thread-safe custom event listeners.
`OllamaClient`	`include/network/ollama_client.hpp` `malama::network::OllamaClient`	HTTP REST and TCP streaming wrapper using Boost.Asio to communicate with the local `ollama serve` daemon over non-blocking sockets.
`StreamWorker`	`include/network/stream_worker.hpp` `malama::network::StreamWorker`	Dedicated background thread wrapper (`std::jthread`) that receives and processes chunked JSON responses into UI events.
`AttachmentManager`	`include/engine/storage/attachment_manager.hpp` `malama::engine::storage::AttachmentManager`	Handles pre-flight staging, binary validation, Base64 conversion, and context tag wrapping for user attachments.
`ParserFactory`	`include/engine/storage/parsers/parser_factory.hpp` `malama::engine::storage::ParserFactory`	Factory pattern implementation routing incoming files to the correct specialized document or image parser based on file extensions.
`HistoryManager`	`include/engine/storage/history_manager.hpp` `malama::engine::storage::HistoryManager`	Provides persistent storage and retrieval for chat sessions, messages, and parameters using transactional SQLite3 queries.
`Pipeline`	`include/engine/markdown/pipeline.hpp` `malama::engine::markdown::Pipeline`	High-speed Markdown-to-HTML transformation engine designed for incremental text updates with an LRU fragment cache.
`TokenEstimator`	`include/engine/token_estimator.hpp` `malama::engine::TokenEstimator`	Calculates prompt and attachment token estimates prior to submission to prevent context window overflow.
`ExportEngine`	`include/engine/export_engine.hpp` `malama::engine::ExportEngine`	Serializes chat history to disk in user-selected formats (.md, .json, .txt).

Need Complete Member Functions and Call Graphs?

Generate full class diagrams, public methods, and call graphs using Doxygen:

doxygen Doxyfile && xdg-open doxygen/html/index.html

Magpiny C++23 Coding Guidelines

Strict architectural constraints enforcing memory safety, readability, and modern C++ usage across the codebase.

Standard File Header

Every .hpp and .cpp file must begin with a standardized header containing the file path, purpose, author contact, creation date, copyright, and GPL-3.0-or-later license.

Standard C++ Source File Header Template

                  // /////////////////////////////////////////////////////////////////////////////
                    // Name:        src/engine/token/token_estimator.cpp
                    // Purpose:     Implements token estimation heuristic calculations
                    // Author:      Magpiny BO 
                    // Created:     2026-08-12
                    // Copyright:   (c) 2026 Magpiny. All rights reserved.
                    // Licence:     GPL-3.0-or-later
                    // /////////////////////////////////////////////////////////////////////////////

Attached Brace Style

K&R attached opening braces are enforced project-wide for all functions, control structures, and class declarations.

Explicit Naming

Interfaces use an I prefix, member variables use m_snake_case, and short variable names (under 3 characters) are disallowed except for standard loop indices.

Right-Aligned Pointers

Pointer and reference indicators are consistently aligned to the variable name (e.g., Type *ptr_name, Type &ref_name).

Zero Exceptions Policy

The core library avoids C++ exceptions. Operations return std::expected<T, ErrorCode> to make error propagation explicit and non-throwing.

Explicit Ownership

Raw owning pointers are prohibited. Dynamic resource lifecycles are managed exclusively through RAII wrappers like std::unique_ptr and std::shared_ptr.

CMake Build Subsystem & Target Graph

Target-based CMake design splitting domain business logic into a static core library.

# Root CMake Target Structure (CMakeLists.txt snippet)
cmake_minimum_required(VERSION 3.28)
project(malama VERSION 0.3.1 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 1. Static Domain Core Target
add_library(malama_core STATIC
    src/config/config_manager.cpp
    src/engine/markdown/pipeline.cpp
    src/engine/storage/attachment_manager.cpp
    src/engine/storage/history_manager.cpp
    src/network/ollama_client.cpp
    src/network/stream_worker.cpp
)

target_link_libraries(malama_core PUBLIC
    SQLite3::SQLite3
    glaze::glaze
    pugixml
    PNG::PNG
    JPEG::JPEG
    PkgConfig::POPPLER_CPP
    spdlog::spdlog
    Boost::cobalt
    LibArchive::LibArchive
)

# 2. Native Graphical Application Target
add_executable(malama src/main.cpp src/ui/main_frame.cpp src/ui/chat_panel.cpp)
target_link_libraries(malama PRIVATE malama_core wxWidgets::wxWidgets)

Automated Testing & Continuous Integration

Offline unit testing using Catch2 v3 paired with cross-distribution container validation.

Catch2 Unit Test Suite

Execute offline component tests covering Base64 transcoding, document MIME detection, attachment queue boundaries, and prompt enclosure tag isolation:

# Run tests using CTest
ctest --test-dir build --output-on-failure

# Execute test target directly
./build/tests/malama_tests "[unit]"

Arch Linux Containerized CI/CD

GitHub Actions uses an archlinux:base-devel container to build, test, and package release binaries under exact compiler environments:

# Local Distro Matrix Execution
cd tests/integration/distro_matrix
./run_matrix.sh --distro arch,fedora,ubuntu

Core Engine Internals &System Architecture Manual