[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7FAMC71EZJEPQJPE4VH8AS8":3,"skill-same:01M7FAMC71EZJEPQJPE4VH8AS8":76},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":32,"ownerHtmlUrl":33,"ownerBlogUrl":6,"ownerDescription":34,"updatedAt":35,"install":36,"resources":49},"01M7FAMC71EZJEPQJPE4VH8AS8","tinystruct-patterns",null,"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\u002Fdispatcher and bin\u002Fdispatcher.cmd launcher scripts when a project lacks them, creating Application classes, @Action-mapped routes, unit tests, ActionRegistry, HTTP\u002FCLI dual-mode handling, the built-in HTTP server, the event system, JSON with Builder\u002FBuilders, database persistence with AbstractData, POJO generation, Server-Sent Events (SSE), file uploads, and outbound HTTP networking.","siddu1004\u002FSFP","siddu1004","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F260113491?v=4","01M7F8W1SAJAR49097VRTE1TW5","Siddhardh Vanguri","01M7F8W1SYGY7JE15AHAECCT9R",5,"MIT","https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: tinystruct-patterns\ndescription: 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\u002Fdispatcher and bin\u002Fdispatcher.cmd launcher scripts when a project lacks them, creating Application classes, @Action-mapped routes, unit tests, ActionRegistry, HTTP\u002FCLI dual-mode handling, the built-in HTTP server, the event system, JSON with Builder\u002FBuilders, database persistence with AbstractData, POJO generation, Server-Sent Events (SSE), file uploads, and outbound HTTP networking.\nmetadata:\n  origin: ECC\n  upstream: tinystruct==1.7.34\n---\n\n# tinystruct Development Patterns\n\nArchitecture 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.\n\n## Core Principle\n\n**CLI and HTTP are equal citizens.** Every method annotated with `@Action` should ideally be runnable from both a terminal and a web browser without modification. This \"dual-mode\" capability is the core design philosophy of tinystruct.\n\n## Primary Development Tool: `bin\u002Fdispatcher`\n\n**`bin\u002Fdispatcher` 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 every `@Action` is dual-mode by design, `bin\u002Fdispatcher` lets you exercise routing, argument binding, and business logic directly from the terminal, with the fastest possible feedback loop and no server\u002Fbrowser required.\n\n```bash\n# Run any @Action directly - the fastest way to verify a new action works\n# (the class must be imported; see --import or default.import.applications in application.properties)\nbin\u002Fdispatcher greet\u002FJames --import com.example.MyService\nbin\u002Fdispatcher echo --words \"Praise the Lord\"\n\n# Start the HTTP server when you need the web-facing counterpart\nbin\u002Fdispatcher start --import org.tinystruct.system.HttpServer\n\n# Import additional Application\u002FMCP classes for the current run\n# (one --import per class; a comma-separated list fails with ClassNotFoundException)\nbin\u002Fdispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyService\n\n# Discover what's available\nbin\u002Fdispatcher --help\nbin\u002Fdispatcher --version\n```\n\nDefault to this workflow: implement the `@Action`, run it immediately via `bin\u002Fdispatcher \u003Caction>` to confirm it behaves correctly in CLI mode, and only start the HTTP server (also via `bin\u002Fdispatcher start ...`) once you need to verify the web-facing path (e.g. `mode = Mode.HTTP_POST`, sessions, file uploads). Never hardcode a `main(String[] args)` as an app's entry point — `bin\u002Fdispatcher` (or `bin\u002Fdispatcher.cmd` on Windows) is the one entry point for every module.\n\n### Generating `bin\u002Fdispatcher` and `bin\u002Fdispatcher.cmd`\n\nEvery tinystruct project needs its launcher in `bin\u002F`. **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\u002F` 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.\n\n**1. Find the tinystruct version** the project builds against: the `\u003Ctinystruct.version>` property or the `org.tinystruct:tinystruct` dependency in `pom.xml`. The jar must be reachable, in `~\u002F.m2\u002Frepository\u002Forg\u002Ftinystruct\u002Ftinystruct\u002F\u003Cversion>\u002F` (run `mvn dependency:resolve` if it is not) or in the project's `lib\u002F`.\n\n**2. From the project root, run the framework once:**\n\n```bash\njava -cp ~\u002F.m2\u002Frepository\u002Forg\u002Ftinystruct\u002Ftinystruct\u002F\u003Cversion>\u002Ftinystruct-\u003Cversion>.jar \\\n     org.tinystruct.system.Dispatcher --version\n```\n\nReplace `\u003Cversion>` with the version found in step 1. On Windows use `%USERPROFILE%\\.m2\\repository\\org\\tinystruct\\tinystruct\\\u003Cversion>\\tinystruct-\u003Cversion>.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:\n\n| Run on | Creates |\n|---|---|\n| Linux, macOS | `bin\u002Fdispatcher` (executable, LF) |\n| Windows | `bin\\dispatcher.cmd` (CRLF) |\n\n**3. Verify.** From the project root run `bin\u002Fdispatcher --version` (Windows: `bin\\dispatcher.cmd --version`). It prints `Dispatcher (cli) (built on tinystruct-\u003Cversion>)`, and the `VERSION` inside the script equals the jar's version. Then `bin\u002Fdispatcher --help` lists the commands and every imported action. Show the user the file you created.\n\n**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\u002Fdispatcher`. Recommended `.gitattributes`, so a checkout does not corrupt the line endings:\n\n```\nbin\u002Fdispatcher     text eol=lf\nbin\u002Fdispatcher.cmd text eol=crlf\n```\n\n**Upgrading tinystruct:** change the version in `pom.xml`, delete the old script, and repeat step 2 with the new jar. Alternatively `bin\u002Fdispatcher 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.\n\n**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\u002Fdispatcher.cmd` into module directories, run them from the build directory: in the surefire configuration set `\u003CworkingDirectory>${project.build.directory}\u003C\u002FworkingDirectory>`.\n\n**What the scripts do**, which explains most problems:\n\n- Run them **from the project root**: the shell script takes the current directory as the root, the `.cmd` takes the parent of `bin\u002F`.\n- The classpath is `target\u002Fclasses`, `lib\u002F*.jar`, `WEB-INF\u002Flib\u002F*`, `WEB-INF\u002Fclasses` and the tinystruct jar (from `lib\u002F`, else `~\u002F.m2`), then they run `org.tinystruct.system.Dispatcher` with your arguments.\n- On the first run, if `mvnw` \u002F `mvnw.cmd` is missing, they extract the Maven Wrapper into the project root (`unzip` on Unix, PowerShell on Windows). Tell the user this happens; the files can be committed or ignored.\n- Only the shell script treats `-D…` and `-X…` arguments as JVM options.\n\n**Gotchas:**\n\n- **On Windows use `bin\\dispatcher.cmd`.** The shell script joins the classpath with `:`, so under Git Bash\u002FMSYS it fails with `ClassNotFoundException: org.tinystruct.system.Dispatcher`. Use WSL, or the `.cmd`.\n- **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\u002F`: `mvn dependency:copy-dependencies -DoutputDirectory=lib` (and git-ignore `lib\u002F`). In a multi-module build, keep the launcher in the directory that holds `target\u002Fclasses` and `lib\u002F`, and copy the sibling modules' jars into that `lib\u002F`; running it from a module whose siblings are not on its classpath fails with `NoClassDefFoundError`.\n- **Load applications with `--import` or configuration.** One `--import` per class (`--import a.A,b.B` fails; write `--import a.A --import b.B`), or list them once in `application.properties`: `default.import.applications=a.A;b.B` (`;`-separated).\n- **`JAVA_HOME` must be set** for the `.cmd`; it stops with an error otherwise.\n- **`bin\u002F` sits directly under the directory that holds `target\u002Fclasses` and `lib\u002F`.** The `.cmd` treats the parent of `bin\u002F` as the root, so a `bin\u002F` nested in the wrong directory puts the wrong classpath in front of `Dispatcher`.\n\n## When to Activate\n\n### When to Use\n\n- Running, testing, or debugging any `@Action` via `bin\u002Fdispatcher` — this is the default way to work with a tinystruct app, before reaching for HTTP or an IDE run configuration.\n- Setting up a project that has no `bin\u002Fdispatcher` \u002F `bin\u002Fdispatcher.cmd` — have the framework generate it (see \"Generating `bin\u002Fdispatcher` and `bin\u002Fdispatcher.cmd`\").\n- Creating new `Application` modules by extending `AbstractApplication`.\n- Defining routes and command-line actions using `@Action`.\n- Handling per-request state via `Context`.\n- Performing JSON serialization using the native `Builder` and `Builders` components.\n- Working with database persistence via `AbstractData` POJOs.\n- Generating POJOs from database tables using the `generate` command, with an XML mapping file or annotations (`--mapping annotation`).\n- Implementing Server-Sent Events (SSE) for real-time push.\n- Handling file uploads via multipart data.\n- Making outbound HTTP requests with `URLRequest` and `HTTPHandler`.\n- Configuring database connections or system settings in `application.properties`.\n- Debugging routing conflicts (Actions) or CLI argument parsing.\n\n## How It Works\n\nThe tinystruct framework treats any method annotated with `@Action` as a routable endpoint for both terminal and web environments. Applications are created by extending `AbstractApplication`, which provides core lifecycle hooks like `init()` and access to the request `Context`.\n\nRouting 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`\u002F`@Column` annotations or XML mapping files for CRUD operations without external ORM libraries. Missing tables can be created automatically with `database.autocreate=true`.\n\n## Examples\n\n### Basic Application (MyService)\n```java\npublic class MyService extends AbstractApplication {\n    @Override\n    public void init() {\n        this.setTemplateRequired(false); \u002F\u002F Disable .view lookup for data\u002FAPI apps\n    }\n\n    @Override public String version() { return \"1.0.0\"; }\n\n    @Action(\"greet\")\n    public String greet() {\n        return \"Hello from tinystruct!\";\n    }\n\n    \u002F\u002F Path parameter: GET \u002F?q=greet\u002FJames  OR  bin\u002Fdispatcher greet\u002FJames\n    @Action(\"greet\")\n    public String greet(String name) {\n        return \"Hello, \" + name + \"!\";\n    }\n}\n```\n\n### HTTP Mode Disambiguation (login)\n```java\n@Action(value = \"login\", mode = Mode.HTTP_POST)\npublic String doLogin(Request\u003C?, ?> request) throws ApplicationException {\n    request.getSession().setAttribute(\"userId\", \"42\");\n    return \"Logged in\";\n}\n```\n\n### Native JSON Data Handling (Builder + Builders)\n```java\nimport org.tinystruct.data.component.Builder;\nimport org.tinystruct.data.component.Builders;\n\n@Action(\"api\u002Fdata\")\npublic String getData() throws ApplicationException {\n    Builders dataList = new Builders();\n    Builder item = new Builder();\n    item.put(\"id\", 1);\n    item.put(\"name\", \"James\");\n    dataList.add(item);\n\n    Builder response = new Builder();\n    response.put(\"status\", \"success\");\n    response.put(\"data\", dataList);\n    return response.toString(); \u002F\u002F {\"status\":\"success\",\"data\":[{\"id\":1,\"name\":\"James\"}]}\n}\n```\n\n### SSE (Server-Sent Events)\n```java\nimport org.tinystruct.http.SSEPushManager;\n\n@Action(\"sse\u002Fconnect\")\npublic String connect() {\n    return \"{\\\"type\\\":\\\"connect\\\",\\\"message\\\":\\\"Connected to SSE\\\"}\";\n}\n\n\u002F\u002F Push to a specific client\nString sessionId = getContext().getId();\nBuilder msg = new Builder();\nmsg.put(\"text\", \"Hello, user!\");\nSSEPushManager.getInstance().push(sessionId, msg);\n\n\u002F\u002F Broadcast to all\n\u002F\u002F Broadcast to all\nSSEPushManager.getInstance().broadcast(msg);\n```\n\n### File Upload\n```java\nimport org.tinystruct.data.FileEntity;\n\n@Action(value = \"upload\", mode = Mode.HTTP_POST)\npublic String upload(Request\u003C?, ?> request) throws ApplicationException {\n    List\u003CFileEntity> files = request.getAttachments();\n    if (files != null) {\n        for (FileEntity file : files) {\n            System.out.println(\"Uploaded: \" + file.getFilename());\n        }\n    }\n    return \"Upload OK\";\n}\n```\n\n### Database Metadata Operations\n`DatabaseOperator` provides direct access to connection-level catalog, schema, and metadata:\n```java\nimport org.tinystruct.data.DatabaseOperator;\n\nDatabaseOperator operator = new DatabaseOperator();\ntry {\n    String catalog = operator.getCatalog();\n    String schema = operator.getSchema();\n    java.sql.DatabaseMetaData metaData = operator.getMetaData();\n    System.out.println(\"Using catalog: \" + catalog + \", schema: \" + schema);\n} finally {\n    operator.close();\n}\n```\n\n## MCP Server and Tools Integration\n\ntinystruct provides native support for the Model Context Protocol (MCP) starting with SDK version **`1.7.0`**.\nThe MCP APIs (e.g., `org.tinystruct.mcp.MCPTool`, `org.tinystruct.mcp.MCPServer`, `org.tinystruct.mcp.MCPException`) are included directly in the core dependency:\n```xml\n\u003Cdependency>\n    \u003CgroupId>org.tinystruct\u003C\u002FgroupId>\n    \u003CartifactId>tinystruct\u003C\u002FartifactId>\n    \u003Cversion>1.7.34\u003C\u002Fversion>\n\u003C\u002Fdependency>\n```\n\n> **SECURITY WARNING (Prompt Injection):**\n> Tool return values are fed directly back into the AI model's context window. You **MUST** validate and sanitize all caller-supplied arguments before including them in the tool's return string. Failure to sanitize inputs can allow an attacker to inject adversarial instructions (Prompt Injection) that override the model's behavior. Always validate length, character sets, and nullity.\n\n**To create an MCP Tool:**\n1. Extend `org.tinystruct.mcp.MCPTool`.\n2. Annotate operations with `@Action` and declare parameters using `@Argument` within the `arguments` array.\n3. Accept parameters as explicit method arguments matching the keys in `@Argument`. (Do **not** use `getContext().getAttribute(...)` for tool arguments).\n\n```java\nimport org.tinystruct.mcp.MCPTool;\nimport org.tinystruct.mcp.MCPException;\nimport org.tinystruct.system.annotation.Action;\nimport org.tinystruct.system.annotation.Argument;\n\npublic class MyCustomTool extends MCPTool {\n    public MyCustomTool() {\n        super(\"custom\", \"A custom tool for demonstrating MCP\");\n    }\n\n    @Action(\n        value = \"custom\u002Fhello\",\n        description = \"Say hello to someone\",\n        arguments = {\n            @Argument(key = \"name\", description = \"The name to greet\", type = \"string\", optional = false)\n        }\n    )\n    public String hello(String name) throws MCPException {\n        \u002F\u002F SECURITY: Validate\u002Fsanitize tool inputs before returning to the model\n        \u002F\u002F to prevent prompt injection vulnerabilities.\n        if (name == null || name.length() > 50 || !name.matches(\"^[a-zA-Z0-9 ]+$\")) {\n            throw new MCPException(\"Invalid name provided\");\n        }\n        return \"Hello, \" + name + \"!\";\n    }\n}\n```\n\n**To deploy an MCP Server:**\n1. Extend `org.tinystruct.mcp.MCPServer`.\n2. Override `init()` and register your tools using `this.registerTool()`. The framework automatically scans and maps the `@Action` methods.\n\n```java\nimport org.tinystruct.mcp.MCPServer;\n\npublic class MyMCPServer extends MCPServer {\n    @Override\n    public void init() {\n        super.init();\n        this.registerTool(new MyCustomTool());\n    }\n\n    @Override\n    public String version() {\n        return \"1.0.0\";\n    }\n}\n```\n\nRun the server via the dispatcher:\n```bash\nbin\u002Fdispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyMCPServer\n```\n\n### Overloaded Tool Methods\ntinystruct supports overloaded methods for the same tool name in `MCPTool` (sharing the same tool name but accepting different parameter signatures).\n- **Schema Merging**: Input schemas of all overloads with the same name are dynamically merged into a unified JSON schema. Properties are unioned, and required properties are intersected (only fields required across *all* overloads remain marked mandatory).\n- **Execution Routing**: When executing a tool, the server iterates sequentially through the available overloaded methods, attempting execution. Each method's schema validation is performed first, and the first overload that validates against the provided arguments successfully executes. If no signature matches or succeeds, the framework throws an appropriate exception.\n\n## Configuration\n\nSettings are managed in `src\u002Fmain\u002Fresources\u002Fapplication.properties`.\n\n```properties\n# Database\ndriver=org.h2.Driver\ndatabase.url=jdbc:h2:~\u002Fmydb\ndatabase.user=sa\ndatabase.password=\n# Optional: create missing tables from the class mapping on first use (off by default)\n# database.autocreate=true\n\n# Server\ndefault.home.page=hello\nserver.port=8080\ndefault.server.open_browser=true\n\n# Locale\ndefault.language=en_US\n\n# Session (Redis for clustered environments)\n# default.session.repository=org.tinystruct.http.RedisSessionRepository\n# redis.host=127.0.0.1\n# redis.port=6379\n\n# Programmatic Logging Configuration\nlogging.enabled=true\nlogging.level=INFO\norg.tinystruct.level=FINE\n```\n\nAccess config values in your application:\n```java\nString port = this.getConfiguration(\"server.port\");\n```\n\n## Logging and Diagnostics\n\nThe framework includes a programmatic wrapper around `java.util.logging` (JUL) that provides beautiful console output and advanced caller tracing out of the box.\n\n- **ANSI Console Colors**: Console output is color-coded based on the log level (red for SEVERE, yellow for WARNING, green for INFO, cyan for CONFIG, and grey for FINE\u002Fdebug logs).\n- **Precise Caller Tracing**: Uses Java's `StackWalker` API to trace the call stack at runtime. It identifies and logs the exact class, method, filename, and line number of the caller that initiated the log (bypassing internal utility and logging layers).\n- **Package\u002FLogger Level Overrides**: Set package-specific overrides directly in `application.properties` (e.g., `org.tinystruct.level=FINE`).\n\n## Red Flags & Anti-patterns\n\n| Symptom | Correct Pattern |\n|---|---|\n| Importing `com.google.gson` or `com.fasterxml.jackson` | Use `org.tinystruct.data.component.Builder` \u002F `Builders`. |\n| Using `List\u003CBuilder>` for JSON arrays | Use `Builders` to avoid generic type erasure issues. |\n| `ApplicationRuntimeException: template not found` | Call `setTemplateRequired(false)` in `init()` for API-only apps. |\n| Annotating `private` methods with `@Action` | Actions must be `public` to be registered by the framework. |\n| Hardcoding `main(String[] args)` in apps, or testing only via curl\u002Fbrowser\u002FIDE run configs | Use `bin\u002Fdispatcher` as the entry point and default dev\u002Ftest tool for all modules. |\n| `bin\u002Fdispatcher` is missing, or a hand-written or copied launcher script | Let the framework generate it: run `org.tinystruct.system.Dispatcher --version` once from the project root (creates the current OS's script). |\n| `bin\u002Fdispatcher` fails with `ClassNotFoundException: org.tinystruct.system.Dispatcher` on Windows | The shell script cannot run under Git Bash\u002FMSYS; use `bin\\dispatcher.cmd` or WSL. |\n| `ClassNotFoundException` for `--import a.A,b.B` | One `--import` per class: `--import a.A --import b.B`. |\n| A shell-script launcher that fails with `\\r: command not found` | The file has CRLF endings; convert `bin\u002Fdispatcher` to LF. |\n| Manual `ActionRegistry` registration | Prefer the `@Action` annotation for automatic discovery. |\n| Action not found at runtime | Ensure class is imported via `--import` or listed in `application.properties`. |\n| CLI arg not visible | Pass with `--key value`; access via `getContext().getAttribute(\"--key\")`. |\n| Two methods same path, wrong one fires | Set explicit `mode` (e.g., `HTTP_GET` vs `HTTP_POST`) to disambiguate. |\n\n## Best Practices\n\n1. **`bin\u002Fdispatcher` first**: Develop and verify against `bin\u002Fdispatcher` before anything else — run the action from the CLI, confirm behavior, then layer on HTTP\u002Fmode concerns. It's the fastest inner-loop and the one tool guaranteed to match how the framework actually routes and binds arguments.\n2. **Granular Applications**: Break logic into smaller, focused applications rather than one monolithic class.\n3. **Setup in `init()`**: Leverage `init()` for setup (config, DB) rather than the constructor. Do NOT call `setAction()` — use `@Action` annotation.\n4. **Mode Awareness**: Use the `Mode` parameter in `@Action` to restrict sensitive operations to `CLI` only or specific HTTP methods.\n5. **Context over Params**: For optional CLI flags, use `getContext().getAttribute(\"--flag\")` rather than adding parameters to the method signature.\n6. **Asynchronous Events**: For heavy tasks triggered by events, use `CompletableFuture.runAsync()` inside the event handler.\n\n## Technical Reference\n\nDetailed guides are available in the `references\u002F` directory:\n\n- [Architecture & Config](references\u002Farchitecture.md) — Abstractions, Package Map, Properties\n- [Routing & @Action](references\u002Frouting.md) — Annotation details, Modes, Parameters\n- [Data Handling](references\u002Fdata-handling.md) — Builder, Builders, JSON serialization & parsing\n- [Database Persistence](references\u002Fdatabase.md) — AbstractData POJOs, CRUD, annotation and XML mapping, POJO generation, table auto-creation\n- [System & Usage](references\u002Fsystem-usage.md) — Context, Sessions, SSE, File Uploads, Events, Networking\n- [Testing Patterns](references\u002Ftesting.md) — JUnit 5 unit and HTTP integration testing\n\n## Reference Source Files (Internal)\n\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002FAbstractApplication.java` — Core base class with lifecycle hooks\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002Fannotation\u002FAction.java` — Annotation & Modes\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fapplication\u002FActionRegistry.java` — Routing Engine\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FBuilder.java` — JSON object serializer\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FBuilders.java` — JSON array serializer\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FAbstractData.java` — Base POJO class with CRUD\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002FMapping.java` — Mapping metadata (annotations or XML), cached per class\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fannotation\u002FTable.java` — `@Table`, with `@Id` and `@Column` alongside it\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Ftools\u002FTableCreator.java` — Creates missing tables (`database.autocreate`)\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Ftools\u002FMySQLGenerator.java` — POJO generator reference (`MappingMode` selects XML or annotations)\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FFieldType.java` — SQL-to-Java type mappings\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FCondition.java` — Fluent SQL query builder\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fhttp\u002FSSEPushManager.java` — SSE connection management\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002Flogging\u002FLogFormatter.java` — Custom log formatter with ANSI console colors and StackWalker-based caller tracing\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002Flogging\u002FLoggerConfigurer.java` — Programmatic logging configurator from application properties\n- `src\u002Ftest\u002Fjava\u002Forg\u002Ftinystruct\u002Fapplication\u002FActionRegistryTest.java` — Registry test examples\n- `src\u002Ftest\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002FHttpServerHttpModeTest.java` — HTTP integration test patterns\n","# tinystruct Development Patterns\n\nArchitecture 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.\n\n## Core Principle\n\n**CLI and HTTP are equal citizens.** Every method annotated with `@Action` should ideally be runnable from both a terminal and a web browser without modification. This \"dual-mode\" capability is the core design philosophy of tinystruct.\n\n## Primary Development Tool: `bin\u002Fdispatcher`\n\n**`bin\u002Fdispatcher` 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 every `@Action` is dual-mode by design, `bin\u002Fdispatcher` lets you exercise routing, argument binding, and business logic directly from the terminal, with the fastest possible feedback loop and no server\u002Fbrowser required.\n\n```bash\n# Run any @Action directly - the fastest way to verify a new action works\n# (the class must be imported; see --import or default.import.applications in application.properties)\nbin\u002Fdispatcher greet\u002FJames --import com.example.MyService\nbin\u002Fdispatcher echo --words \"Praise the Lord\"\n\n# Start the HTTP server when you need the web-facing counterpart\nbin\u002Fdispatcher start --import org.tinystruct.system.HttpServer\n\n# Import additional Application\u002FMCP classes for the current run\n# (one --import per class; a comma-separated list fails with ClassNotFoundException)\nbin\u002Fdispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyService\n\n# Discover what's available\nbin\u002Fdispatcher --help\nbin\u002Fdispatcher --version\n```\n\nDefault to this workflow: implement the `@Action`, run it immediately via `bin\u002Fdispatcher \u003Caction>` to confirm it behaves correctly in CLI mode, and only start the HTTP server (also via `bin\u002Fdispatcher start ...`) once you need to verify the web-facing path (e.g. `mode = Mode.HTTP_POST`, sessions, file uploads). Never hardcode a `main(String[] args)` as an app's entry point — `bin\u002Fdispatcher` (or `bin\u002Fdispatcher.cmd` on Windows) is the one entry point for every module.\n\n### Generating `bin\u002Fdispatcher` and `bin\u002Fdispatcher.cmd`\n\nEvery tinystruct project needs its launcher in `bin\u002F`. **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\u002F` 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.\n\n**1. Find the tinystruct version** the project builds against: the `\u003Ctinystruct.version>` property or the `org.tinystruct:tinystruct` dependency in `pom.xml`. The jar must be reachable, in `~\u002F.m2\u002Frepository\u002Forg\u002Ftinystruct\u002Ftinystruct\u002F\u003Cversion>\u002F` (run `mvn dependency:resolve` if it is not) or in the project's `lib\u002F`.\n\n**2. From the project root, run the framework once:**\n\n```bash\njava -cp ~\u002F.m2\u002Frepository\u002Forg\u002Ftinystruct\u002Ftinystruct\u002F\u003Cversion>\u002Ftinystruct-\u003Cversion>.jar \\\n     org.tinystruct.system.Dispatcher --version\n```\n\nReplace `\u003Cversion>` with the version found in step 1. On Windows use `%USERPROFILE%\\.m2\\repository\\org\\tinystruct\\tinystruct\\\u003Cversion>\\tinystruct-\u003Cversion>.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:\n\n| Run on | Creates |\n|---|---|\n| Linux, macOS | `bin\u002Fdispatcher` (executable, LF) |\n| Windows | `bin\\dispatcher.cmd` (CRLF) |\n\n**3. Verify.** From the project root run `bin\u002Fdispatcher --version` (Windows: `bin\\dispatcher.cmd --version`). It prints `Dispatcher (cli) (built on tinystruct-\u003Cversion>)`, and the `VERSION` inside the script equals the jar's version. Then `bin\u002Fdispatcher --help` lists the commands and every imported action. Show the user the file you created.\n\n**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\u002Fdispatcher`. Recommended `.gitattributes`, so a checkout does not corrupt the line endings:\n\n```\nbin\u002Fdispatcher     text eol=lf\nbin\u002Fdispatcher.cmd text eol=crlf\n```\n\n**Upgrading tinystruct:** change the version in `pom.xml`, delete the old script, and repeat step 2 with the new jar. Alternatively `bin\u002Fdispatcher 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.\n\n**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\u002Fdispatcher.cmd` into module directories, run them from the build directory: in the surefire configuration set `\u003CworkingDirectory>${project.build.directory}\u003C\u002FworkingDirectory>`.\n\n**What the scripts do**, which explains most problems:\n\n- Run them **from the project root**: the shell script takes the current directory as the root, the `.cmd` takes the parent of `bin\u002F`.\n- The classpath is `target\u002Fclasses`, `lib\u002F*.jar`, `WEB-INF\u002Flib\u002F*`, `WEB-INF\u002Fclasses` and the tinystruct jar (from `lib\u002F`, else `~\u002F.m2`), then they run `org.tinystruct.system.Dispatcher` with your arguments.\n- On the first run, if `mvnw` \u002F `mvnw.cmd` is missing, they extract the Maven Wrapper into the project root (`unzip` on Unix, PowerShell on Windows). Tell the user this happens; the files can be committed or ignored.\n- Only the shell script treats `-D…` and `-X…` arguments as JVM options.\n\n**Gotchas:**\n\n- **On Windows use `bin\\dispatcher.cmd`.** The shell script joins the classpath with `:`, so under Git Bash\u002FMSYS it fails with `ClassNotFoundException: org.tinystruct.system.Dispatcher`. Use WSL, or the `.cmd`.\n- **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\u002F`: `mvn dependency:copy-dependencies -DoutputDirectory=lib` (and git-ignore `lib\u002F`). In a multi-module build, keep the launcher in the directory that holds `target\u002Fclasses` and `lib\u002F`, and copy the sibling modules' jars into that `lib\u002F`; running it from a module whose siblings are not on its classpath fails with `NoClassDefFoundError`.\n- **Load applications with `--import` or configuration.** One `--import` per class (`--import a.A,b.B` fails; write `--import a.A --import b.B`), or list them once in `application.properties`: `default.import.applications=a.A;b.B` (`;`-separated).\n- **`JAVA_HOME` must be set** for the `.cmd`; it stops with an error otherwise.\n- **`bin\u002F` sits directly under the directory that holds `target\u002Fclasses` and `lib\u002F`.** The `.cmd` treats the parent of `bin\u002F` as the root, so a `bin\u002F` nested in the wrong directory puts the wrong classpath in front of `Dispatcher`.\n\n## When to Activate\n\n### When to Use\n\n- Running, testing, or debugging any `@Action` via `bin\u002Fdispatcher` — this is the default way to work with a tinystruct app, before reaching for HTTP or an IDE run configuration.\n- Setting up a project that has no `bin\u002Fdispatcher` \u002F `bin\u002Fdispatcher.cmd` — have the framework generate it (see \"Generating `bin\u002Fdispatcher` and `bin\u002Fdispatcher.cmd`\").\n- Creating new `Application` modules by extending `AbstractApplication`.\n- Defining routes and command-line actions using `@Action`.\n- Handling per-request state via `Context`.\n- Performing JSON serialization using the native `Builder` and `Builders` components.\n- Working with database persistence via `AbstractData` POJOs.\n- Generating POJOs from database tables using the `generate` command, with an XML mapping file or annotations (`--mapping annotation`).\n- Implementing Server-Sent Events (SSE) for real-time push.\n- Handling file uploads via multipart data.\n- Making outbound HTTP requests with `URLRequest` and `HTTPHandler`.\n- Configuring database connections or system settings in `application.properties`.\n- Debugging routing conflicts (Actions) or CLI argument parsing.\n\n## How It Works\n\nThe tinystruct framework treats any method annotated with `@Action` as a routable endpoint for both terminal and web environments. Applications are created by extending `AbstractApplication`, which provides core lifecycle hooks like `init()` and access to the request `Context`.\n\nRouting 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`\u002F`@Column` annotations or XML mapping files for CRUD operations without external ORM libraries. Missing tables can be created automatically with `database.autocreate=true`.\n\n## Examples\n\n### Basic Application (MyService)\n```java\npublic class MyService extends AbstractApplication {\n    @Override\n    public void init() {\n        this.setTemplateRequired(false); \u002F\u002F Disable .view lookup for data\u002FAPI apps\n    }\n\n    @Override public String version() { return \"1.0.0\"; }\n\n    @Action(\"greet\")\n    public String greet() {\n        return \"Hello from tinystruct!\";\n    }\n\n    \u002F\u002F Path parameter: GET \u002F?q=greet\u002FJames  OR  bin\u002Fdispatcher greet\u002FJames\n    @Action(\"greet\")\n    public String greet(String name) {\n        return \"Hello, \" + name + \"!\";\n    }\n}\n```\n\n### HTTP Mode Disambiguation (login)\n```java\n@Action(value = \"login\", mode = Mode.HTTP_POST)\npublic String doLogin(Request\u003C?, ?> request) throws ApplicationException {\n    request.getSession().setAttribute(\"userId\", \"42\");\n    return \"Logged in\";\n}\n```\n\n### Native JSON Data Handling (Builder + Builders)\n```java\nimport org.tinystruct.data.component.Builder;\nimport org.tinystruct.data.component.Builders;\n\n@Action(\"api\u002Fdata\")\npublic String getData() throws ApplicationException {\n    Builders dataList = new Builders();\n    Builder item = new Builder();\n    item.put(\"id\", 1);\n    item.put(\"name\", \"James\");\n    dataList.add(item);\n\n    Builder response = new Builder();\n    response.put(\"status\", \"success\");\n    response.put(\"data\", dataList);\n    return response.toString(); \u002F\u002F {\"status\":\"success\",\"data\":[{\"id\":1,\"name\":\"James\"}]}\n}\n```\n\n### SSE (Server-Sent Events)\n```java\nimport org.tinystruct.http.SSEPushManager;\n\n@Action(\"sse\u002Fconnect\")\npublic String connect() {\n    return \"{\\\"type\\\":\\\"connect\\\",\\\"message\\\":\\\"Connected to SSE\\\"}\";\n}\n\n\u002F\u002F Push to a specific client\nString sessionId = getContext().getId();\nBuilder msg = new Builder();\nmsg.put(\"text\", \"Hello, user!\");\nSSEPushManager.getInstance().push(sessionId, msg);\n\n\u002F\u002F Broadcast to all\n\u002F\u002F Broadcast to all\nSSEPushManager.getInstance().broadcast(msg);\n```\n\n### File Upload\n```java\nimport org.tinystruct.data.FileEntity;\n\n@Action(value = \"upload\", mode = Mode.HTTP_POST)\npublic String upload(Request\u003C?, ?> request) throws ApplicationException {\n    List\u003CFileEntity> files = request.getAttachments();\n    if (files != null) {\n        for (FileEntity file : files) {\n            System.out.println(\"Uploaded: \" + file.getFilename());\n        }\n    }\n    return \"Upload OK\";\n}\n```\n\n### Database Metadata Operations\n`DatabaseOperator` provides direct access to connection-level catalog, schema, and metadata:\n```java\nimport org.tinystruct.data.DatabaseOperator;\n\nDatabaseOperator operator = new DatabaseOperator();\ntry {\n    String catalog = operator.getCatalog();\n    String schema = operator.getSchema();\n    java.sql.DatabaseMetaData metaData = operator.getMetaData();\n    System.out.println(\"Using catalog: \" + catalog + \", schema: \" + schema);\n} finally {\n    operator.close();\n}\n```\n\n## MCP Server and Tools Integration\n\ntinystruct provides native support for the Model Context Protocol (MCP) starting with SDK version **`1.7.0`**.\nThe MCP APIs (e.g., `org.tinystruct.mcp.MCPTool`, `org.tinystruct.mcp.MCPServer`, `org.tinystruct.mcp.MCPException`) are included directly in the core dependency:\n```xml\n\u003Cdependency>\n    \u003CgroupId>org.tinystruct\u003C\u002FgroupId>\n    \u003CartifactId>tinystruct\u003C\u002FartifactId>\n    \u003Cversion>1.7.34\u003C\u002Fversion>\n\u003C\u002Fdependency>\n```\n\n> **SECURITY WARNING (Prompt Injection):**\n> Tool return values are fed directly back into the AI model's context window. You **MUST** validate and sanitize all caller-supplied arguments before including them in the tool's return string. Failure to sanitize inputs can allow an attacker to inject adversarial instructions (Prompt Injection) that override the model's behavior. Always validate length, character sets, and nullity.\n\n**To create an MCP Tool:**\n1. Extend `org.tinystruct.mcp.MCPTool`.\n2. Annotate operations with `@Action` and declare parameters using `@Argument` within the `arguments` array.\n3. Accept parameters as explicit method arguments matching the keys in `@Argument`. (Do **not** use `getContext().getAttribute(...)` for tool arguments).\n\n```java\nimport org.tinystruct.mcp.MCPTool;\nimport org.tinystruct.mcp.MCPException;\nimport org.tinystruct.system.annotation.Action;\nimport org.tinystruct.system.annotation.Argument;\n\npublic class MyCustomTool extends MCPTool {\n    public MyCustomTool() {\n        super(\"custom\", \"A custom tool for demonstrating MCP\");\n    }\n\n    @Action(\n        value = \"custom\u002Fhello\",\n        description = \"Say hello to someone\",\n        arguments = {\n            @Argument(key = \"name\", description = \"The name to greet\", type = \"string\", optional = false)\n        }\n    )\n    public String hello(String name) throws MCPException {\n        \u002F\u002F SECURITY: Validate\u002Fsanitize tool inputs before returning to the model\n        \u002F\u002F to prevent prompt injection vulnerabilities.\n        if (name == null || name.length() > 50 || !name.matches(\"^[a-zA-Z0-9 ]+$\")) {\n            throw new MCPException(\"Invalid name provided\");\n        }\n        return \"Hello, \" + name + \"!\";\n    }\n}\n```\n\n**To deploy an MCP Server:**\n1. Extend `org.tinystruct.mcp.MCPServer`.\n2. Override `init()` and register your tools using `this.registerTool()`. The framework automatically scans and maps the `@Action` methods.\n\n```java\nimport org.tinystruct.mcp.MCPServer;\n\npublic class MyMCPServer extends MCPServer {\n    @Override\n    public void init() {\n        super.init();\n        this.registerTool(new MyCustomTool());\n    }\n\n    @Override\n    public String version() {\n        return \"1.0.0\";\n    }\n}\n```\n\nRun the server via the dispatcher:\n```bash\nbin\u002Fdispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyMCPServer\n```\n\n### Overloaded Tool Methods\ntinystruct supports overloaded methods for the same tool name in `MCPTool` (sharing the same tool name but accepting different parameter signatures).\n- **Schema Merging**: Input schemas of all overloads with the same name are dynamically merged into a unified JSON schema. Properties are unioned, and required properties are intersected (only fields required across *all* overloads remain marked mandatory).\n- **Execution Routing**: When executing a tool, the server iterates sequentially through the available overloaded methods, attempting execution. Each method's schema validation is performed first, and the first overload that validates against the provided arguments successfully executes. If no signature matches or succeeds, the framework throws an appropriate exception.\n\n## Configuration\n\nSettings are managed in `src\u002Fmain\u002Fresources\u002Fapplication.properties`.\n\n```properties\n# Database\ndriver=org.h2.Driver\ndatabase.url=jdbc:h2:~\u002Fmydb\ndatabase.user=sa\ndatabase.password=\n# Optional: create missing tables from the class mapping on first use (off by default)\n# database.autocreate=true\n\n# Server\ndefault.home.page=hello\nserver.port=8080\ndefault.server.open_browser=true\n\n# Locale\ndefault.language=en_US\n\n# Session (Redis for clustered environments)\n# default.session.repository=org.tinystruct.http.RedisSessionRepository\n# redis.host=127.0.0.1\n# redis.port=6379\n\n# Programmatic Logging Configuration\nlogging.enabled=true\nlogging.level=INFO\norg.tinystruct.level=FINE\n```\n\nAccess config values in your application:\n```java\nString port = this.getConfiguration(\"server.port\");\n```\n\n## Logging and Diagnostics\n\nThe framework includes a programmatic wrapper around `java.util.logging` (JUL) that provides beautiful console output and advanced caller tracing out of the box.\n\n- **ANSI Console Colors**: Console output is color-coded based on the log level (red for SEVERE, yellow for WARNING, green for INFO, cyan for CONFIG, and grey for FINE\u002Fdebug logs).\n- **Precise Caller Tracing**: Uses Java's `StackWalker` API to trace the call stack at runtime. It identifies and logs the exact class, method, filename, and line number of the caller that initiated the log (bypassing internal utility and logging layers).\n- **Package\u002FLogger Level Overrides**: Set package-specific overrides directly in `application.properties` (e.g., `org.tinystruct.level=FINE`).\n\n## Red Flags & Anti-patterns\n\n| Symptom | Correct Pattern |\n|---|---|\n| Importing `com.google.gson` or `com.fasterxml.jackson` | Use `org.tinystruct.data.component.Builder` \u002F `Builders`. |\n| Using `List\u003CBuilder>` for JSON arrays | Use `Builders` to avoid generic type erasure issues. |\n| `ApplicationRuntimeException: template not found` | Call `setTemplateRequired(false)` in `init()` for API-only apps. |\n| Annotating `private` methods with `@Action` | Actions must be `public` to be registered by the framework. |\n| Hardcoding `main(String[] args)` in apps, or testing only via curl\u002Fbrowser\u002FIDE run configs | Use `bin\u002Fdispatcher` as the entry point and default dev\u002Ftest tool for all modules. |\n| `bin\u002Fdispatcher` is missing, or a hand-written or copied launcher script | Let the framework generate it: run `org.tinystruct.system.Dispatcher --version` once from the project root (creates the current OS's script). |\n| `bin\u002Fdispatcher` fails with `ClassNotFoundException: org.tinystruct.system.Dispatcher` on Windows | The shell script cannot run under Git Bash\u002FMSYS; use `bin\\dispatcher.cmd` or WSL. |\n| `ClassNotFoundException` for `--import a.A,b.B` | One `--import` per class: `--import a.A --import b.B`. |\n| A shell-script launcher that fails with `\\r: command not found` | The file has CRLF endings; convert `bin\u002Fdispatcher` to LF. |\n| Manual `ActionRegistry` registration | Prefer the `@Action` annotation for automatic discovery. |\n| Action not found at runtime | Ensure class is imported via `--import` or listed in `application.properties`. |\n| CLI arg not visible | Pass with `--key value`; access via `getContext().getAttribute(\"--key\")`. |\n| Two methods same path, wrong one fires | Set explicit `mode` (e.g., `HTTP_GET` vs `HTTP_POST`) to disambiguate. |\n\n## Best Practices\n\n1. **`bin\u002Fdispatcher` first**: Develop and verify against `bin\u002Fdispatcher` before anything else — run the action from the CLI, confirm behavior, then layer on HTTP\u002Fmode concerns. It's the fastest inner-loop and the one tool guaranteed to match how the framework actually routes and binds arguments.\n2. **Granular Applications**: Break logic into smaller, focused applications rather than one monolithic class.\n3. **Setup in `init()`**: Leverage `init()` for setup (config, DB) rather than the constructor. Do NOT call `setAction()` — use `@Action` annotation.\n4. **Mode Awareness**: Use the `Mode` parameter in `@Action` to restrict sensitive operations to `CLI` only or specific HTTP methods.\n5. **Context over Params**: For optional CLI flags, use `getContext().getAttribute(\"--flag\")` rather than adding parameters to the method signature.\n6. **Asynchronous Events**: For heavy tasks triggered by events, use `CompletableFuture.runAsync()` inside the event handler.\n\n## Technical Reference\n\nDetailed guides are available in the `references\u002F` directory:\n\n- [Architecture & Config](references\u002Farchitecture.md) — Abstractions, Package Map, Properties\n- [Routing & @Action](references\u002Frouting.md) — Annotation details, Modes, Parameters\n- [Data Handling](references\u002Fdata-handling.md) — Builder, Builders, JSON serialization & parsing\n- [Database Persistence](references\u002Fdatabase.md) — AbstractData POJOs, CRUD, annotation and XML mapping, POJO generation, table auto-creation\n- [System & Usage](references\u002Fsystem-usage.md) — Context, Sessions, SSE, File Uploads, Events, Networking\n- [Testing Patterns](references\u002Ftesting.md) — JUnit 5 unit and HTTP integration testing\n\n## Reference Source Files (Internal)\n\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002FAbstractApplication.java` — Core base class with lifecycle hooks\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002Fannotation\u002FAction.java` — Annotation & Modes\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fapplication\u002FActionRegistry.java` — Routing Engine\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FBuilder.java` — JSON object serializer\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FBuilders.java` — JSON array serializer\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FAbstractData.java` — Base POJO class with CRUD\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002FMapping.java` — Mapping metadata (annotations or XML), cached per class\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fannotation\u002FTable.java` — `@Table`, with `@Id` and `@Column` alongside it\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Ftools\u002FTableCreator.java` — Creates missing tables (`database.autocreate`)\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Ftools\u002FMySQLGenerator.java` — POJO generator reference (`MappingMode` selects XML or annotations)\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FFieldType.java` — SQL-to-Java type mappings\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fdata\u002Fcomponent\u002FCondition.java` — Fluent SQL query builder\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fhttp\u002FSSEPushManager.java` — SSE connection management\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002Flogging\u002FLogFormatter.java` — Custom log formatter with ANSI console colors and StackWalker-based caller tracing\n- `src\u002Fmain\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002Flogging\u002FLoggerConfigurer.java` — Programmatic logging configurator from application properties\n- `src\u002Ftest\u002Fjava\u002Forg\u002Ftinystruct\u002Fapplication\u002FActionRegistryTest.java` — Registry test examples\n- `src\u002Ftest\u002Fjava\u002Forg\u002Ftinystruct\u002Fsystem\u002FHttpServerHttpModeTest.java` — HTTP integration test patterns\n",{"name":5,"metadata":24,"description":7},{"origin":25,"upstream":26},"ECC","tinystruct==1.7.34","main","15fa5201935d2b1d172b4e61c2360c908d876d20","plugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns",0,"https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP","https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fsfp-hive","https:\u002F\u002Fgithub.com\u002Fsiddu1004","I am a student at Amrita Vishwa Vidyapeetham pursuing my BTECH degree in Electronics and Electrical Engineering (2024-2028).","2026-11-09 16:04:40",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add siddu1004\u002FSFP --skill tinystruct-patterns",{"tool":42,"command":43},"bunx","bunx skills add siddu1004\u002FSFP --skill tinystruct-patterns",{"tool":45,"command":46},"pnpm","pnpm dlx skills add siddu1004\u002FSFP --skill tinystruct-patterns","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002FSKILL.md",true,[50,56,60,64,68,72],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Farchitecture.md","REFERENCE","参考文档",4283,"https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002Freferences\u002Farchitecture.md",{"path":57,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fdata-handling.md",1893,"https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002Freferences\u002Fdata-handling.md",{"path":61,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fdatabase.md",7371,"https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002Freferences\u002Fdatabase.md",{"path":65,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Frouting.md",2477,"https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002Freferences\u002Frouting.md",{"path":69,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fsystem-usage.md",2881,"https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002Freferences\u002Fsystem-usage.md",{"path":73,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Ftesting.md",1988,"https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fbackend\u002Fskills\u002Ftinystruct-patterns\u002Freferences\u002Ftesting.md",[77,84,91,98,105,112],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7FEEDADZBNBVY19H3XZKCBQ","scientific-schematics","Generates scientific diagram drafts using Nano Banana 2 AI with smart iterative refinement. Uses Gemini 3.7 Flash for quality review. Refines when the review requests improvement, with at most two generations. Specialized in neural network architectures, system diagrams, flowcharts, biological pathways, and complex scientific visualizations.","https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fscience-hardware\u002Fskills\u002Fscientific-schematics\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7FEE0JS04FE58MST48D0MMC","polyhaven-texture-apply","Apply realistic PBR textures from PolyHaven to any Blender object. Supports metals, wood, concrete, fabric, and more. Trigger when asked to texture an object, apply a material from PolyHaven, make something look like metal\u002Fwood\u002Fmarble, or change object surface.","https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fscience-hardware\u002Fskills\u002Fpolyhaven-texture-apply\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":19},"01M7FEDJRWV194TY411WVRS84W","polyhaven-studio-setup","Set up a professional product photography studio in Blender using PolyHaven HDRIs and PBR ground materials. Trigger when asked to create a studio setup, add HDRI lighting, set up product photography, or create a showroom scene.","https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fscience-hardware\u002Fskills\u002Fpolyhaven-studio-setup\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":19},"01M7FED5H2FGS50XGETMGSM0RV","polyhaven-scene-builder","Build complete product scenes using PolyHaven assets — HDRI environment, textured ground\u002Fpedestal, and optional props from the 3D model library. Trigger when asked to build a product scene, create a showcase setup, add a pedestal, or compose a product shot.","https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fscience-hardware\u002Fskills\u002Fpolyhaven-scene-builder\u002FSKILL.md",[],[],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":19},"01M7FECSNZ2CJA7Z8TPE5R844R","polyhaven-material-swap","Cycle through multiple PolyHaven materials on a product and render each variant. Great for showing color\u002Ffinish options. Trigger when asked to show material variants, swap textures, create color options, show finish comparisons, or render product in different materials.","https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fscience-hardware\u002Fskills\u002Fpolyhaven-material-swap\u002FSKILL.md",[],[],{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":19},"01M7FECBPQ6YWH48PYAMS0C5CE","polyhaven-hdri-showcase","Render the same product across multiple HDRI environments and output a comparison grid. Trigger when asked to compare lighting setups, test different environments, show product in multiple settings, or create an HDRI comparison.","https:\u002F\u002Fgithub.com\u002Fsiddu1004\u002FSFP\u002Fblob\u002Fmain\u002Fplugins\u002Fscience-hardware\u002Fskills\u002Fpolyhaven-hdri-showcase\u002FSKILL.md",[],[]]