# arkforgelabs/astra architecture

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

- Interactive diagram: https://gitdiagram.com/arkforgelabs/astra
- Repository: https://github.com/arkforgelabs/astra

## Overview

##### Project type and purpose
- Astra is an open-source, high-performance web server runtime written in Rust that embeds a Lua VM (supports Lua 5.1–5.4, Luau, LuaJIT).
- It exposes an HTTP server API to user-provided Lua scripts, plus database drivers, templating, crypto, file I/O, async tasks, and an HTTP client.

##### File structure
- Top level:
- Cargo.toml, src/main.rs – the Rust binary entrypoint.
- src/components – the modular Rust implementation of HTTP server, HTTP client, database, crypto, file I/O, templating, global functions.
- src/lua – glue code and built-in Lua libraries loaded into the Lua VM.
- examples – sample Lua scripts and templates.
- docs – static site for user documentation (not part of the runtime).
- Workflows and build scripts:
- .github/workflows – CI for publishing crates and building releases.
- astra_build.lua, pack.lua – custom build/packaging scripts for the Lua side.
- Configuration:
- cliff.toml – CLI argument parsing config.
- Tera templates under examples/templates.

##### README for additional insights
- Core features: HTTP server with request/response model, routing, middleware, database connectivity, templating, async tasks.
- Usage pattern: instantiate `Astra.http.server`, register Lua callbacks for routes, configure server (port, middleware), run server.
- Deployment: delivered as a cargo-installed or prebuilt binary.

##### Important elements
- Clear component names matching file paths (e.g. “src/components/http/server”).
- Optional: denote the build pipeline (Cargo → binary) and CI/CD on the side if desired.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Rust Host"
        direction TB
        Main["Rust Core Binary\n(src/main.rs)"]:::host
        CLI["CLI Arg Parsing\n(cliff.toml, src/commands.rs)"]:::host
        CompMgr["Component Manager\n(src/components/mod.rs)"]:::host
        HTTPServer["HTTP Server Module\n(src/components/http/server/)"]:::host
        HTTPClient["HTTP Client Module\n(src/components/http/client/mod.rs)"]:::host
        Database["Database Modules\n(src/components/database.rs)"]:::host
        Templating["Templating Engine\n(src/components/tera_templating.rs)"]:::host
        Crypto["Crypto Module\n(src/components/crypto.rs)"]:::host
        FileIO["File I/O Module\n(src/components/fileio.rs)"]:::host
        GlobalFns["Global Functions\n(src/components/global_functions.rs)"]:::host
        Async["Async Task Scheduler"]:::host
    end

    subgraph "Lua VM"
        direction TB
        Glue["Glue & Built-in libs\n(src/lua/astra.lua,\n src/lua/astra_bundle.lua,\n src/lua/libs/)"]:::guest
        UserScripts["User Lua Scripts\n(examples/)"]:::guest
    end

    subgraph "External Systems"
        direction TB
        Incoming["Incoming HTTP Request"]:::ext
        ExtHTTP["External HTTP Service"]:::ext
        ExtDB["Database (PostgreSQL/SQLite)"]:::ext
        FS["File System"]:::ext
    end

    Incoming -->|TCP| HTTPServer
    HTTPServer -->|"dispatch request"| Glue
    Glue -->|"call Lua handler"| UserScripts
    UserScripts -->|"invoke APIs"| CompMgr
    CompMgr --> HTTPClient
    CompMgr --> Database
    CompMgr --> Templating
    CompMgr --> Crypto
    CompMgr --> FileIO
    CompMgr --> GlobalFns
    CompMgr --> Async
    HTTPClient -->|HTTP request| ExtHTTP
    Database -->|db:execute| ExtDB
    FileIO -->|read/write| FS
    UserScripts -->|"build response"| Glue
    Glue -->|"send response"| HTTPServer
    HTTPServer -->|HTTP response| Incoming

    Main --> CLI
    Main --> CompMgr
    CompMgr --> Glue

    click Main "https://github.com/arkforgelabs/astra/blob/main/src/main.rs"
    click CLI "https://github.com/arkforgelabs/astra/blob/main/cliff.toml"
    click CLI "https://github.com/arkforgelabs/astra/blob/main/src/commands.rs"
    click CompMgr "https://github.com/arkforgelabs/astra/blob/main/src/components/mod.rs"
    click Glue "https://github.com/arkforgelabs/astra/blob/main/src/lua/astra.lua"
    click Glue "https://github.com/arkforgelabs/astra/blob/main/src/lua/astra_bundle.lua"
    click Glue "https://github.com/arkforgelabs/astra/tree/main/src/lua/libs/"
    click HTTPServer "https://github.com/arkforgelabs/astra/tree/main/src/components/http/server/"
    click HTTPClient "https://github.com/arkforgelabs/astra/blob/main/src/components/http/client/mod.rs"
    click Database "https://github.com/arkforgelabs/astra/blob/main/src/components/database.rs"
    click Templating "https://github.com/arkforgelabs/astra/blob/main/src/components/tera_templating.rs"
    click Crypto "https://github.com/arkforgelabs/astra/blob/main/src/components/crypto.rs"
    click FileIO "https://github.com/arkforgelabs/astra/blob/main/src/components/fileio.rs"
    click GlobalFns "https://github.com/arkforgelabs/astra/blob/main/src/components/global_functions.rs"

    classDef host fill:#D0E8FF,stroke:#005B96,color:#000;
    classDef guest fill:#E8FFD0,stroke:#5B9600,color:#000;
    classDef ext fill:#F0F0F0,stroke:#888,color:#000
```
