# guille-ux/sysarena architecture

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

- Interactive diagram: https://gitdiagram.com/guille-ux/sysarena
- Repository: https://github.com/guille-ux/sysarena

## Overview

##### Project Type and Purpose
- This is a low‐level C library (“SysArena”) implementing a dynamic memory manager based on arenas, intended for bare-metal or custom OS/embedded environments.
- It is an open-source tool (no runtime server or frontend), distributed as source, static libraries, and Debian packages.

##### Main Components
a. Core Library (src/sysarena.c, include/*.h)
- Arena: single block allocator (base, size, used, in_use)
- ArenaManager (“sysarena”): manages an array of Arenas, supports split, merge, defragment, alloc, free
b. Public API (include/sysarena.h, include/types.h)
- Exposes functions: poor_arena_init, arena_init/alloc/free, sysarena_init/alloc/free/split/defrag
c. Examples (examples/example.c)
- Demonstrates linking against libsysarena.a and calling the API
d. Build & Distribution
- Makefiles at root, src, packages directory
- Dist folder: prebuilt zip, npm-style package.json (for Node packager?)
- Debian packaging under packages/debian
e. Packaging outputs (packages/build/libsysarena.a, packages/debian/usr/lib/libsysarena.a)

##### Relationships and Interactions
- Client code → (includes) → Public API headers → (links) → Core Library
- Core Library internally orchestrates:
- ArenaManager data structures (array of Arena structs)
- Calls to arena_init / arena_alloc / arena_free
- On sysarena_alloc: traverses arenas, may split or merge via arena_split / arena_merge
- On sysarena_defragment: merges adjacent free arenas
- Build system → compiles src/sysarena.c → static library → linked by examples or end projects

##### Architectural Patterns & Design Principles
- Modular C library: separation of public headers vs. private implementation
- Single-process, in-memory data structures (no threads, no IPC)
- Layered:
- Low level: Arena operations
- Higher level: ArenaManager (sysarena_*)
- Static linking for bare-metal; no dynamic dependencies

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    ClientApp["Client Application"]:::external
    ClientApp -->|"#include + link libsysarena.a"| PublicAPI

    %% Public API
    PublicAPI["Public API Headers"]:::api
    PublicAPI -->|uses| SysArenaLibrary

    %% SysArena Library Container
    subgraph "SysArena Library (bare-metal, no libc)"
        direction TB
        ArenaModule["Arena Module\n(arena_init/alloc/free)"]:::internal
        ArenaManagerModule["ArenaManager Module\n(sysarena_init/alloc/free/split/defrag)"]:::internal
        ArenaManagerModule -->|calls| ArenaModule
        ArenaManagerModule -->|manages| ArenaInstances["Arena Instances\n(base, size, used, in_use)"]:::data
    end
    PublicAPI -->|links| SysArenaLibrary

    %% Build System
    subgraph "Build System" 
        direction TB
        RootMake["Makefile"]:::build
        RootMake -->|compiles src/sysarena.c| CompileStep["Compilation"]:::build
        CompileStep -->|creates| StaticLibBuild["packages/build/libsysarena.a"]:::build
        CompileStep -->|packages| DebianPkgDir["packages/debian"]:::build
    end

    %% Debian Packaging
    subgraph "Debian Packaging"
        direction TB
        DebianRules["rules"]:::build
        DebianControl["control"]:::build
        DebianChangelog["changelog"]:::build
        DebianRules --> DebianControl
        DebianControl --> DebianChangelog
        DebianPkgDir --> DebianRules
        DebianPkgDir -->|"includes"| DebianHeaders["usr/include"]:::api
        DebianHeaders --> DebianSysarenaH["sysarena.h"]:::api
        DebianHeaders --> DebianTypesH["types.h"]:::api
        DebianPkgDir -->|"libs"| DebianLib["usr/lib/libsysarena.a"]:::build
    end

    %% Distribution
    subgraph "Distribution"
        direction TB
        DistZip["dist/sysarena.zip"]:::dist
        DistSrcFolder["dist/sysarena"]:::dist
        DistSrcFolder --> DistSrcSysarenaC["src/src/sysarena.c"]:::internal
        DistSrcFolder --> DistSrcHeaders["src/include"]:::api
        DistSrcHeaders --> DistSrcSysarenaH["sysarena.h"]:::api
        DistSrcHeaders --> DistSrcTypesH["types.h"]:::api
        DistSrcFolder --> DistPackageJSON["package.json"]:::dist
    end

    %% Examples
    ClientApp -->|example| ExampleCode["examples/example.c"]:::external

    %% Legend / Data Node
    style ArenaInstances fill:#e0ffe0,stroke:#0a0,type:dash

    %% Click events
    click ArenaModule "https://github.com/guille-ux/sysarena/blob/master/src/sysarena.c"
    click ArenaManagerModule "https://github.com/guille-ux/sysarena/blob/master/src/sysarena.c"
    click PublicAPI "https://github.com/guille-ux/sysarena/blob/master/include/sysarena.h"
    click PublicAPI "https://github.com/guille-ux/sysarena/blob/master/include/types.h"
    click ExampleCode "https://github.com/guille-ux/sysarena/blob/master/examples/example.c"
    click RootMake "https://github.com/guille-ux/sysarena/tree/master/Makefile"
    click DistZip "https://github.com/guille-ux/sysarena/blob/master/dist/sysarena.zip"
    click DistSrcSysarenaC "https://github.com/guille-ux/sysarena/blob/master/dist/sysarena/src/src/sysarena.c"
    click DistSrcSysarenaH "https://github.com/guille-ux/sysarena/blob/master/dist/sysarena/src/include/sysarena.h"
    click DistSrcTypesH "https://github.com/guille-ux/sysarena/blob/master/dist/sysarena/src/include/types.h"
    click DistPackageJSON "https://github.com/guille-ux/sysarena/blob/master/dist/sysarena/package.json"
    click DebianRules "https://github.com/guille-ux/sysarena/tree/master/packages/debian/rules"
    click DebianControl "https://github.com/guille-ux/sysarena/tree/master/packages/debian/control"
    click DebianChangelog "https://github.com/guille-ux/sysarena/tree/master/packages/debian/changelog"
    click DebianSysarenaH "https://github.com/guille-ux/sysarena/blob/master/packages/debian/usr/include/sysarena.h"
    click DebianTypesH "https://github.com/guille-ux/sysarena/blob/master/packages/debian/usr/include/types.h"
    click DebianLib "https://github.com/guille-ux/sysarena/blob/master/packages/debian/usr/lib/libsysarena.a"
    click StaticLibBuild "https://github.com/guille-ux/sysarena/blob/master/packages/build/libsysarena.a"
    click BuildHelpers1 "https://github.com/guille-ux/sysarena/tree/master/packages/Makefile"
    click BuildHelpers2 "https://github.com/guille-ux/sysarena/tree/master/packages/VERSION"

    %% Styles
    classDef external fill:#fff2cc,stroke:#e6b800
    classDef api fill:#cce5ff,stroke:#3399ff
    classDef internal fill:#d5f5e3,stroke:#28a745
    classDef build fill:#e0e0e0,stroke:#6c757d
    classDef dist fill:#f3e5f5,stroke:#9c27b0
    classDef data fill:#f0fff0,stroke:#33cc33
```
