Tinystruct Patterns
Scaffold or extend tinystruct Java apps where CLI commands and HTTP routes share one ActionRegistry dispatch model.
Overview
Tinystruct Patterns is an agent skill for the Build phase that documents tinystruct’s ActionRegistry architecture so agents route CLI and HTTP handlers consistently in Java.
Install
npx skills add https://github.com/affaan-m/everything-claude-code --skill tinystruct-patternsWhat is this skill?
- Singleton ActionRegistry maps URL patterns and command strings to Action MethodHandles
- @Action annotation as the single routing primitive for web and CLI
- Extend AbstractApplication; per-request state via Context
- Dispatcher CLI entry with --import; built-in HttpServer start pattern
- Package map for org.tinystruct core types (Application, Action, Dispatcher)
- Documents 6+ core abstractions in the architecture table (AbstractApplication through HttpServer)
Adoption & trust: 1.2k installs on skills.sh; 210k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You picked tinystruct but your agent keeps guessing wrong entry classes, routing annotations, or how CLI imports relate to the HTTP server.
Who is it for?
Indie backends and CLI tools in Java that need one codebase for HTTP APIs and command-line utilities.
Skip if: Greenfield teams standardizing on Spring Boot or Kotlin-only stacks without tinystruct in the repo.
When should I use this skill?
User builds or refactors tinystruct Java apps, dual CLI/HTTP dispatch, or asks how ActionRegistry routing works.
What do I get? / Deliverables
Your agent extends AbstractApplication, registers @Action routes, and starts Dispatcher or HttpServer using the documented package map and singleton registry rules.
- Correctly structured AbstractApplication subclasses
- Registered @Action endpoints for CLI and/or HTTP
Recommended Skills
Journey fit
Framework architecture and routing patterns belong in Build when you are implementing services and CLIs, not when you are still validating the idea. Backend subphase covers server entry points, routing, and request context—the core of tinystruct’s dual CLI/HTTP design.
How it compares
Architecture reference for one framework—not a generic REST design or DevOps deploy skill.
Common Questions / FAQ
Who is tinystruct-patterns for?
Solo Java builders and agents implementing tinystruct microservices, CLIs, or small HTTP services who need correct framework vocabulary.
When should I use tinystruct-patterns?
During Build backend work when adding routes, wiring Dispatcher --import, or starting the built-in HttpServer.
Is tinystruct-patterns safe to install?
It is documentation-only patterns; review Security Audits on this Prism page for the parent skill package before install.
SKILL.md
READMESKILL.md - Tinystruct Patterns
# 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 ```java @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 ```java @Action("hello") public String hello() { return "Hello, tinystruct!"; } ``` **Execution via Dispatcher:** ```bash 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`: ```java String port = this.getConfiguration("server.port"); ``` # tinystruct Data Handling (JSON) ## When to Use Prefer `org.tinystruct.data.component.Builder` and `Builders` for lightweight, zero-dependency JSON. Use `Builder` for JSON obje