Architecture

Understanding Ninja's core components and design.

System Components

ShurikenManager

The central component responsible for:

• Installing and removing shurikens
• Starting and stopping services
• Managing configuration and state
• Tracking processes and lock files

Ninja Engine

Lua scripting engine providing:

• Filesystem APIs (fs)
• Process management (proc)
• Shell execution (shell)
• Environment access (env)
• Logging (log)

Used for:

• Management scripts (start(), stop() functions)
• Post-install scripts
• Custom tools
• DSL command processing

Armory

Package repository storing .shuriken files with:

• CBOR-encoded metadata
• Tar.gz archived files
• SHA-256 signatures

Directory Structure

~/.ninja/
├── shurikens/           # Installed services
│   └── {name}/
│       ├── .ninja/      # Ninja metadata
│       │   ├── manifest.toml
│       │   ├── options.toml
│       │   ├── config.tmpl
│       │   ├── shuriken.lck
│       │   └── *.ns     # Management scripts
│       └── [service files]
├── projects/            # Application data
└── blacksmith/          # Built packages

Package Format

.shuriken binary structure:

[MAGIC]            6 bytes  - "HSRZEG"
[metadata_length]  2 bytes  - u16 LE
[metadata]         N bytes  - CBOR
[archive_length]   4 bytes  - u32 LE
[archive]          N bytes  - tar.gz
[signature]        32 bytes - SHA-256

Management Types

Native Management (Deprecated)

Spawns a binary as a child process:

• Tracks PID and start time
• Creates lock file with process info
• Verifies PID + start time before termination

Script Management (Recommended)

Executes Lua scripts with start() and stop() functions:

• Full control over lifecycle
• Access to Ninja APIs
• Platform-specific logic
• Custom health checks

State Management

Shuriken states:

• Idle - Not running
• Running - Active service

Lock file (.ninja/shuriken.lck):

{
  "name": "service-name",
  "type": "Native" | "Script",
  "pid": 12345,          // Native only
  "start_time": 1638360000  // Native only
}

Configuration System

Template rendering flow:

1. Load options.toml (user values)
2. Inject {{ platform }} and {{ root }}
3. Render config.tmpl with Tera
4. Write to path from manifest.toml

See Templater for details.

APIs and Interfaces

• CLI - shurikenctl command-line tool
• GUI - Next.js + Tauri desktop application
• HTTP / GraphQL API - Automation and CI/CD integration
• DSL - Interactive command language
• MCP - Tool integration for automation

Architecture Highlights

• Modular design - CLI, GUI, HTTP, and FFI pieces can be used independently
• Rust core - Memory-safe and fast service management engine
• Lua scripting - Shurikens can embed custom logic and modules
• Cross-platform - Linux, macOS, and Windows support with platform-specific behavior
• Extensible - Shurikens, tools, and scripting hooks adapt to different infrastructure

See also: API Reference, DSL Syntax