"How many are your works, O LORD ! In wisdom you made them all; the earth is full of your creatures."
Psalms 104:24
Language: English | Português (Brasil) | 简体中文 | 繁體中文 | 日本語 | 한국어 | Türkçe | Русский | Tiếng Việt | ไทย | Deutsch | Español
The tinystruct framework
A simple framework for Java development. Simple thinking, Better design, Easy to be used with better performance!
Prerequisites
- Java Development Kit (JDK) 17 or higher
- Maven (for dependency management)
- A text editor or IDE (IntelliJ IDEA, Eclipse, VS Code, etc.)
Getting Started with tinystruct archetype
You can follow this archetype to create a tinystruct-based project quickly: https://github.com/tinystruct/tinystruct-archetype
Or create a project with a single command (Linux/macOS, requires JDK 17+ and Maven; choose basic, web, mcp, workflow or agent):
curl -fsSL https://tinystruct.org/create | sh
On Windows (requires Git for Windows or WSL), run this in PowerShell:
irm https://tinystruct.org/create.ps1 | iex
Installation and Getting Started Manually
- Add the dependency into your pom.xml.
<dependency>
<groupId>org.tinystruct</groupId>
<artifactId>tinystruct</artifactId>
<version>1.7.35</version>
</dependency>
To use the framework as a standalone command-line tool, build the optional jar that bundles all dependencies (about 50 MB, not part of the release):
./mvnw package -Pstandalone # Windows: mvnw.cmd package -Pstandalone
java -jar target/tinystruct-1.7.35-jar-with-dependencies.jar --help
- Extend the AbstractApplication in Java:
package tinystruct.examples;
import org.tinystruct.AbstractApplication;
import org.tinystruct.ApplicationException;
import org.tinystruct.system.annotation.Action;
public class example extends AbstractApplication {
@Override
public void init() {
// TODO Auto-generated method stub
}
@Override
public String version() {
return "1.0";
}
@Action("praise")
public String praise() {
return "Praise the Lord!";
}
@Action("say")
public String say() throws ApplicationException {
if (null != getContext().getAttribute("--words"))
return getContext().getAttribute("--words").toString();
throw new ApplicationException("Could not find the parameter <i>words</i>.");
}
@Action("say")
public String say(String words) {
return words;
}
@Action(value = "hello", mode = Mode.HTTP_GET)
public String helloGet() {
return "GET";
}
@Action(value = "hello", mode = Mode.HTTP_POST)
public String helloPost() {
return "POST";
}
}
Smalltalk: https://github.com/tinystruct/smalltalk
Execute in CLI mode
$ bin/dispatcher --version
_/ ' _ _/ _ _ _/
/ / /) (/ _) / / (/ ( / 1.7.35
/
$ bin/dispatcher --help
Usage: bin/dispatcher COMMAND [OPTIONS]
A command line tool for tinystruct framework
Commands:
download Download a resource from other servers
exec To execute native command(s)
generate POJO object generator
install Install a package
maven-wrapper Extract Maven Wrapper
open Start a default browser to open the specific URL
say Output words
set Set system property
sql-execute Executes the given SQL statement, which may be an INSERT, UPDATE, DELETE, or DDL statement
sql-query Executes the given SQL statement, which returns a single ResultSet object
update Update for latest version
Options:
--allow-remote-access Allow to be accessed remotely
--help Help command
--host Host name / IP
--import Import application
--logo Print logo
--settings Print settings
--version Print version
Run 'bin/dispatcher COMMAND --help' for more information on a command.
$ bin/dispatcher say/"Praise the Lord"
Praise the Lord
$ bin/dispatcher say --words Hello --import tinystruct.examples.example
Hello
Run it in a http server
# bin/dispatcher start --import org.tinystruct.system.HttpServer
You can access the below URLs:
Performance Test
$ wrk -t12 -c400 -d30s "http://127.0.0.1:8080/?q=say/Praise the Lord!"
Running 30s test @ http://127.0.0.1:8080/?q=say/Praise the Lord!
12 threads and 400 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 17.44ms 33.42ms 377.73ms 88.98%
Req/Sec 7.27k 1.66k 13.55k 69.94%
2604473 requests in 30.02s, 524.09MB read
Requests/sec: 86753.98
Transfer/sec: 17.46MB
Handling over 86,000 requests per second with low average latency (~17.44ms), indicating the endpoint is highly efficient under heavy load. this shows the raw power and efficiency of the tinystruct framework. But it's not just about the performance numbers. It's about the philosophy behind it.
What makes tinystruct framework modern?
-
No
main()method required Applications can be started directly using CLI commands likebin/dispatcher, with no boilerplate code needed. This removes unnecessary ceremony from the development lifecycle. -
Unified design for CLI and Web Unlike Spring Boot which is primarily web-centric, tinystruct treats CLI and Web as equal citizens. This makes it perfect for AI tasks, script automation, and hybrid applications — all from the same codebase.
-
Built-in lightweight HTTP server Whether it’s Netty or Tomcat, tinystruct integrates the server lifecycle inside the framework. There's no need for separate containers or complicated configuration files. Just import what you need and run.
-
Minimal configuration philosophy Configuration is minimized to the essentials. You don't need to wire up hundreds of beans, and there's no excessive XML or YAML involved. This improves developer productivity and reduces bugs.
-
Annotation-based routing The framework provides a clean and intuitive routing mechanism using
@Action, eliminating the need for overly complex controller hierarchies. -
Performance-first architecture There’s almost zero overhead. No reflection-based bean scanning, no auto-wiring maze, no unnecessary interceptors unless explicitly enabled. This translates into faster response times and smaller memory footprint.
-
Developer empowerment without complexity With tinystruct, developers are free to focus on real business logic rather than fighting with framework mechanics. It's designed to be transparent, predictable, and extensible — all without sacrificing control or performance.
Architecture
License
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
