everything-claude-code/skills/tinystruct-patterns/references/architecture.md

tinystruct Architecture and Configuration

When to Use

Choose tinystruct when you need a lightweight, high-performance Java framework that treats CLI and HTTP as equal citizens. Ideal for microservices, CLI utilities, and data-driven applications with a small footprint and zero-dependency JSON handling.

How It Works

Core Architecture

The framework operates on a singleton ActionRegistry that maps URL patterns (or command strings) to Action objects. When a request arrives, the system resolves the path and invokes the corresponding method handle.

Key Abstractions

Class/Interface	Role
AbstractApplication	Base class for all tinystruct applications. Extend this.
@Action annotation	Maps a method to a URI path (web) or command name (CLI). The single routing primitive.
ActionRegistry	Singleton that maps URL patterns to Action objects via regex. Never instantiate directly.
Action	Wraps a MethodHandle + regex pattern + priority + Mode for dispatch.
Context	Per-request state store. Access via getContext(). Holds CLI args and HTTP request/response.
Dispatcher	CLI entry point (bin/dispatcher). Reads --import to load applications.
HttpServer	Built-in HTTP server. Start with bin/dispatcher start --import org.tinystruct.system.HttpServer.

Package Map

org.tinystruct/
├── AbstractApplication.java      ← extend this
├── Application.java              ← interface
├── ApplicationException.java     ← checked exception
├── ApplicationRuntimeException.java ← unchecked exception
├── application/
│   ├── Action.java               ← runtime action wrapper
│   ├── ActionRegistry.java       ← singleton route registry
│   └── Context.java              ← request context
├── system/
│   ├── annotation/Action.java    ← @Action annotation + Mode enum
│   ├── Dispatcher.java           ← CLI dispatcher
│   ├── HttpServer.java           ← built-in HTTP server
│   ├── EventDispatcher.java      ← event bus
│   └── Settings.java             ← reads application.properties
├── data/
│   ├── component/Builder.java    ← JSON object (use instead of Gson/Jackson)
│   ├── component/Builders.java   ← JSON array
│   ├── component/AbstractData.java ← base POJO for DB persistence
│   ├── component/Condition.java  ← fluent SQL query builder
│   ├── component/FieldType.java  ← SQL-to-Java type mappings
│   ├── Mapping.java              ← reads .map.xml metadata
│   ├── DatabaseOperator.java     ← low-level JDBC wrapper
│   └── FileEntity.java           ← file upload representation
├── http/                         ← Request, Response, Constants
│   └── SSEPushManager.java       ← Server-Sent Events management
└── net/                          ← URLRequest, HTTPHandler (outbound HTTP)

Template Behavior and Dispatch Flow

By default, the framework assumes a view template is required. If templateRequired is true, toString() looks for a .view file in src/main/resources/themes/<ClassName>.view. Use setVariable("name", value) to pass data to templates, which use {%name%} for interpolation.

Examples

Minimal Application Initialization

@Override
public void init() {
    this.setTemplateRequired(false); // Skip .view template lookup for data-only apps
    // Do NOT call setAction() here — use @Action annotation instead
}

Action Definition and CLI Invocation

@Action("hello")
public String hello() {
    return "Hello, tinystruct!";
}

Execution via Dispatcher:

bin/dispatcher hello
bin/dispatcher greet/James
bin/dispatcher echo --words "Hello" --import com.example.HelloApp

Configuration Access

Located at src/main/resources/application.properties:

String port = this.getConfiguration("server.port");