Expert guidance for developing with the tinystruct Java framework. Use when working on the tinystruct codebase or any project built on tinystruct — including creating Application classes, @Action-mapped routes, unit tests, ActionRegistry, HTTP/CLI dual-mode handling, the built-in HTTP server, the ev

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. 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. When to Activate When to Use Creating new Application modules by extending AbstractApplication . Defining routes and command line actions using @Action . Handling per request state via Context . Performing JSON serialization using the native Builder and Builders components. Working with database persistence via AbstractData POJOs. Generating POJOs from database tables using the generate command. Implementing Server Sent Events (SSE) for real time push. Handling file uploads via multipart data. Making outbound HTTP requests with URLRequest and HTTPHandler . 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 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 . 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 paired with XML mapping files for CRUD operations without external ORM libraries. Examples Basic Application (MyService) HTTP Mode Disambiguation (login) Native JSON Data Handling (Builder + Builders) SSE (Server Sent Events) File Upload MCP Server and Tools Integration tinystruct provides native support for the Model Context Protocol (MCP) starting with SDK version 1.7.26 . The MCP APIs (e.g., org.tinystruct.mcp.MCPTool , org.tinystruct.mcp.MCPServer , org.tinystruct.mcp.MCPException ) are included directly in the core dependency: SECURITY WARNING (Prompt Injection): 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. To create an MCP Tool: 1. Extend org.tinystruct.mcp.MCPTool . 2. Annotate operations with @Action and declare parameters using @Argument within the arguments array. 3. Accept parameters as explicit method arguments matching the keys in @Argument . (Do not use getContext().getAttribute(...) for tool arguments). To deploy an MCP Server: 1. Extend org.tinystruct.mcp.MCPServer . 2. Override init() and register your tools using this.registerTool() . The framework automatically scans and maps the @Action methods. Run the server via the dispatcher: Configuration Settings are managed in src/main/resources/application.properties . Access config values in your application: Red Flags & Anti patterns Symptom Correct Pattern Importing com.google.gson or com.fasterxml.jackson Use org.tinystruct.data.component.Builder / Builders . Using List<Builder for JSON arrays Use Builders to avoid generic type erasure issues. ApplicationRuntimeException: template not found Call setTemplateRequired(false) in init() for API only apps. Annotating private methods with @Action Actions must be public to be registered by the framework. Hardcoding main(String[] args) in apps Use bin/dispatcher as the entry point for all modules. Manual ActionRegistry registration Prefer the @Action annotation for automatic discovery. Action not found at runtime Ensure class is imported via import or listed in application.properties . CLI arg not visible Pass with key value ; access via getContext().getAttribute(" key") . Two methods same path, wrong one fires Set explicit mode (e.g., HTTP GET vs HTTP POST ) to disambiguate. Best Practices 1. Granular Applications : Break logic into smaller, focused applications rather than one monolithic class. 2. Setup in init() : Leverage init() for setup (config, DB) rather than the constructor. Do NOT call setAction() — use @Action annotation. 3. Mode Awareness : Use the Mode parameter in @Action to restrict sensitive operations to CLI only or specific HTTP methods. 4. Context over Params : For optional CLI flags, use getContext().getAttribute(" flag") rather than adding parameters to the method signature. 5. Asynchronous Events : For heavy tasks triggered by events, use CompletableFuture.runAsync() inside the event handler. Technical Reference Detailed guides are available in the references/ directory: [Architecture & Config](references/architecture.md) — Abstractions, Package Map, Properties [Routing & @Action](references/routing.md) — Annotation details, Modes, Parameters [Data Handling](references/data handling.md) — Builder, Builders, JSON serialization & parsing [Database Persistence](references/database.md) — AbstractData POJOs, CRUD, mapping XML, POJO generation [System & Usage](references/system usage.md) — Context, Sessions, SSE, File Uploads, Events, Networking [Testing Patterns](references/testing.md) — JUnit 5 unit and HTTP integration testing Reference Source Files (Internal) src/main/java/org/tinystruct/AbstractApplication.java — Core base class with lifecycle hooks src/main/java/org/tinystruct/system/annotation/Action.java — Annotation & Modes src/main/java/org/tinystruct/application/ActionRegistry.java — Routing Engine src/main/java/org/tinystruct/data/component/Builder.java — JSON object serializer src/main/java/org/tinystruct/data/component/Builders.java — JSON array serializer src/main/java/org/tinystruct/data/component/AbstractData.java — Base POJO class with CRUD src/main/java/org/tinystruct/data/Mapping.java — Mapping XML parser src/main/java/org/tinystruct/data/tools/MySQLGenerator.java — POJO generator reference src/main/java/org/tinystruct/data/component/FieldType.java — SQL to Java type mappings src/main/java/org/tinystruct/data/component/Condition.java — Fluent SQL query builder src/main/java/org/tinystruct/http/SSEPushManager.java — SSE connection management src/test/java/org/tinystruct/application/ActionRegistryTest.java — Registry test examples src/test/java/org/tinystruct/system/HttpServerHttpModeTest.java — HTTP integration test patterns

tinystruct-patterns