affaan-m/everything-claude-code/tinystruct-patterns
Claude Code and agent skill by affaan-m/everything-claude-code
- community
- ext:[{"type":"hook","description":"Pre/post lifecycle hooks"}]
Checking that the SKILL.md file is still in the repository.
Expert guidance for developing with the tinystruct Java framework. Use when working on the tinystruct codebase or any project built on tinystruct — including generating the bin/dispatcher and bin/dispatcher.cmd launcher scripts when a project lacks them, creating Application classes, @Action-mapped routes, unit tests, ActionRegistry, HTTP/CLI dual-mode handling, the built-in HTTP server, the event system, JSON with Builder/Builders, database persistence with AbstractData, POJO generation, Server-Sent Events (SSE), file uploads, and outbound HTTP networking.
Install
npx vskill@latest install affaan-m/everything-claude-code/tinystruct-patternsSemi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard
SKILL.md
The same SKILL.md was published earlier as affaan-m/everything-claude-code/tinystruct-patterns.
tinystruct Development Patterns
Architecture and implementation patterns for building modules with the tinystruct Java framework – a lightweight, high-performance framework that treats CLI and HTTP as equal citizens, requiring no main() method and minimal configuration.
Core Principle
CLI and HTTP are equal citizens. A transport-neutral @Action uses Mode.DEFAULT (or omits mode) and has no HTTP-only dependencies. Such an action can run from both a terminal and a web browser. Mode.DEFAULT removes the transport restriction; it does not make an HTTP-dependent method CLI-compatible. Request and Response parameters come from HTTP context attributes and remain null when those attributes are absent, as in an ordinary CLI invocation. Keep shared logic independent of HTTP objects, sessions, and uploads, and call it from transport-specific entry points when needed. This "dual-mode" capability is the core design philosophy of tinystruct. An action with a transport-specific mode (Mode.CLI, Mode.HTTP_GET, Mode.HTTP_POST, ...) is deliberately bound to that transport: the framework rejects it from the other one with "The action is not allowed to be executed."
Primary Development Tool: bin/dispatcher
`bin/dispatcher` is the default, highest-priority tool for developing, running, testing, and debugging a tinystruct application — reach for it before an IDE run configuration, a hand-written `main()`, curl, or a browser. Because transport-neutral @Action methods are dual-mode by design, bin/dispatcher lets you exercise routing, argument binding, and business logic directly from the terminal, with the fastest possible feedback loop and no server/browser required. Actions bound to an HTTP method (Mode.HTTP_POST, Mode.HTTP_GET, ...) cannot be reached from bin/dispatcher; test those through an HTTP client against the running server.
Default to this workflow: implement a transport-neutral @Action, run it immediately via bin/dispatcher <action> to confirm it behaves correctly in CLI mode, and only start the HTTP server (also via bin/dispatcher start ...) once you need to verify the web-facing path (e.g. mode = Mode.HTTP_POST, sessions, file uploads). For HTTP-only actions skip the CLI step and test them over HTTP; for Mode.CLI actions no server is needed. Never hardcode a main(String[] args) as an app's entry point — bin/dispatcher (or bin/dispatcher.cmd on Windows) is the one entry point for every module.
Generating bin/dispatcher and bin/dispatcher.cmd
Every tinystruct project needs its launcher in bin/. The framework generates it — never write it by hand, and never copy it from another project or substitute a `main()`. ApplicationManager.init() writes the launcher for the current operating system into bin/ under the working directory whenever it is missing, from templates inside the tinystruct jar, with that jar's version filled in. Line endings and the executable bit are already right.
1. Find the tinystruct version the project builds against: the <tinystruct.version> property or the org.tinystruct:tinystruct dependency in pom.xml. The jar must be reachable, in ~/.m2/repository/org/tinystruct/tinystruct/<version>/ (run mvn dependency:resolve if it is not) or in the project's lib/.
2. From the project root, run the framework once:
Replace <version> with the version found in step 1. On Windows use %USERPROFILE%\.m2\repository\org\tinystruct\tinystruct\<version>\tinystruct-<version>.jar and the same class. This creates only the script for the OS you ran it on, and only if it is not already there:
| Run on | Creates | |
|---|---|---|
| Linux, macOS | bin/dispatcher (executable, LF) | |
| Windows | bin\dispatcher.cmd (CRLF) |
3. Verify. From the project root run bin/dispatcher --version (Windows: bin\dispatcher.cmd --version). It prints Dispatcher (cli) (built on tinystruct-<version>), and the VERSION inside the script equals the jar's version. Then bin/dispatcher --help lists the commands and every imported action. Show the user the file you created.
4. Get both scripts by running step 2 on each OS, or let a teammate or CI on the other OS run it and commit the result. Commit both, so a checkout on either OS works. Do not try to fake the other OS with -Dos.name=…: on Windows it fails (UnsupportedOperationException from setPosixFilePermissions) and leaves an empty bin/dispatcher. Recommended .gitattributes, so a checkout does not corrupt the line endings:
Upgrading tinystruct: change the version in pom.xml, delete the old script, and repeat step 2 with the new jar. Alternatively bin/dispatcher update checks Maven Central for the latest release, upgrades the project's dependency and regenerates the script with force; it needs the network, edits the pom.xml, and goes to the latest version, not a chosen one.
It also happens implicitly. Any code that reaches ApplicationManager.init() (the dispatcher itself, or ApplicationManager.install(app, config) in a unit test) creates the script in the current directory if it is missing. If unit tests scatter bin/dispatcher.cmd into module directories, run them from the build directory: in the surefire configuration set <workingDirectory>${project.build.directory}</workingDirectory>.
What the scripts do, which explains most problems:
- Run them from the project root: the shell script takes the current directory as the root, the
.cmdtakes the parent ofbin/. - The classpath is
target/classes,lib/*.jar,WEB-INF/lib/*,WEB-INF/classesand the tinystruct jar (fromlib/, else~/.m2), then they runorg.tinystruct.system.Dispatcherwith your arguments. - On the first run, if
mvnw/mvnw.cmdis missing, they extract the Maven Wrapper into the project root (unzipon Unix, PowerShell on Windows). Tell the user this happens; the files can be committed or ignored. - Only the shell script treats
-D…and-X…arguments as JVM options.
Gotchas:
- On Windows use `bin\dispatcher.cmd`. The shell script joins the classpath with
:, so under Git Bash/MSYS it fails withClassNotFoundException: org.tinystruct.system.Dispatcher. Use WSL, or the.cmd. - Only the tinystruct jar is on the classpath. The framework no longer ships a fat jar by default, so your other modules, JDBC drivers and libraries (jjwt, lettuce, …) must be in
lib/:mvn dependency:copy-dependencies -DoutputDirectory=lib(and git-ignorelib/). In a multi-module build, keep the launcher in the directory that holdstarget/classesandlib/, and copy the sibling modules' jars into thatlib/; running it from a module whose siblings are not on its classpath fails withNoClassDefFoundError. - Load applications with `--import` or configuration. One
--importper class (--import a.A,b.Bfails; write--import a.A --import b.B), or list them once inapplication.properties:default.import.applications=a.A;b.B(;-separated). - `JAVA_HOME` must be set for the
.cmd; it stops with an error otherwise. - `bin/` sits directly under the directory that holds `target/classes` and `lib/`. The
.cmdtreats the parent ofbin/as the root, so abin/nested in the wrong directory puts the wrong classpath in front ofDispatcher.
When to Activate
When to Use
- Running, testing, or debugging any transport-neutral or
Mode.CLI@Actionviabin/dispatcher— this is the default way to work with a tinystruct app, before reaching for HTTP or an IDE run configuration. HTTP-only actions are tested over HTTP instead. - Setting up a project that has no
bin/dispatcher/bin/dispatcher.cmd— have the framework generate it (see "Generatingbin/dispatcherandbin/dispatcher.cmd"). - Creating new
Applicationmodules by extendingAbstractApplication. - Defining routes and command-line actions using
@Action. - Handling per-request state via
Context. - Performing JSON serialization using the native
BuilderandBuilderscomponents. - Working with database persistence via
AbstractDataPOJOs. - Generating POJOs from database tables using the
generatecommand, with an XML mapping file or annotations (--mapping annotation). - Implementing Server-Sent Events (SSE) for real-time push.
- Handling file uploads via multipart data.
- Making outbound HTTP requests with
URLRequestandHTTPHandler. - Configuring database connections or system settings in
application.properties. - Debugging routing conflicts (Actions) or CLI argument parsing.
How It Works
The tinystruct framework treats any method annotated with @Action as a routable endpoint. Without a mode, dispatch is not restricted to one transport, but its parameters and implementation still need to support that environment. Ordinary CLI calls do not supply HTTP Request or Response objects. With mode = Mode.CLI or an HTTP mode such as Mode.HTTP_POST, dispatch is restricted to that transport. Applications are created by extending AbstractApplication, which provides core lifecycle hooks like init() and access to the request Context.
Routing is handled by the ActionRegistry, which automatically maps path segments to method arguments and injects dependencies. For data-only services, the native Builder and Builders components should be used for JSON serialization to maintain a zero-dependency footprint. The database layer uses AbstractData POJOs mapped to tables with @Table/@Column annotations or XML mapping files for CRUD operations without external ORM libraries. Missing tables can be created automatically with database.autocreate=true.
Examples
Basic Application (MyService)
HTTP Mode Disambiguation (login)
The limits below are example application policy measured in UTF-16 code units, not tinystruct defaults. Align them with your authentication service. Reject blank credentials without trimming or otherwise changing the values passed to authentication.
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/tinystruct-patterns/SKILL.md
Popularity
- Repository stars
- 183,249
- Repository forks
- 28,243
- Repository npm downloads, 7 days
- 1,728
- 7-day trend score
- 78
Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 15 May 2026, 6 months ago.
Extension points
hookPre/post lifecycle hooks
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/affaan-m/everything-claude-code/tinystruct-patterns)