diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cf14738..bc9e545 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -51,6 +51,9 @@ jobs:
       - name: Compile
         run: make compile
 
+      - name: Compile example
+        run: rebar3 as test compile
+
       - name: Run tests
         run: make test
 
diff --git a/README.md b/README.md
index 08d31c9..8cfdad2 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@ ElliOpts = [
 {ok, Pid} = elli:start_link(ElliOpts).
 ```
 
-See `src/elli_openapi_demo.erl` for example handler implementations.
+See the `example/` directory for a runnable example application with handler implementations.
 
 ## Handler Functions
 
@@ -73,13 +73,20 @@ To return different status codes from the same handler, use union types in your
     | {404, Headers3, NotFoundBody}.
 ```
 
-For complete handler examples, see `src/elli_openapi_demo.erl`.
+For complete handler examples, see `example/src/elli_openapi_demo.erl`.
 
-## Demo
+## Example Application
 
-To try out the demo application:
+The `example/` directory contains a runnable demo application showcasing multiple handler implementations including user management, echo, status updates, and item updates with conflict detection.
+
+To run the example:
 
 ```bash
-rebar3 compile
+cd example
 rebar3 shell
 ```
+
+The demo starts on port 3000. Access the API documentation at:
+- Swagger UI: http://localhost:3000/swagger
+- ReDoc: http://localhost:3000/redoc
+- OpenAPI JSON: http://localhost:3000/api-docs
diff --git a/demo.escript b/demo.escript
deleted file mode 100644
index bacdd06..0000000
--- a/demo.escript
+++ /dev/null
@@ -1,27 +0,0 @@
-#!/usr/bin/env escript
-%% -*- erlang -*-
-%%! -pa _build/default/lib/*/ebin
-
-main(_) ->
-    Routes = [
-%%      {<<"POST">>, <<"/api/users">>, fun elli_openapi_demo:create_user/3},
-%%      {<<"GET">>, <<"/api/users/{userId}">>, fun elli_openapi_demo:get_user/3},
-%%      {<<"POST">>, <<"/api/echo">>, fun elli_openapi_demo:echo_text/3},
-%%      {<<"PUT">>, <<"/api/items/{itemId}">>, fun elli_openapi_demo:update_item/3}
-        {<<"GET">>, <<"/api/users/{userId}">>, fun user_handler:get_user/3},
-        {<<"POST">>, <<"/api/users/">>, fun user_handler:create_user/3}
-    ],
-    Port = 3000,
-    ElliOpts = [
-        {callback, elli_openapi_handler},
-        {callback_args, Routes},
-        {port, Port}
-    ],
-
-    %% Start Elli
-    case elli:start_link(ElliOpts) of
-        {ok, _Pid} ->
-            io:format("Elli openapi is started. Access the API documentation at: http://localhost:~p/swagger~n", [Port]);
-        {error, Reason} ->
-            io:format("Failed to start Elli server: ~p~n~n", [Reason])
-    end.
diff --git a/example/demo.escript b/example/demo.escript
new file mode 100644
index 0000000..2758d8c
--- /dev/null
+++ b/example/demo.escript
@@ -0,0 +1,31 @@
+#!/usr/bin/env escript
+%% -*- erlang -*-
+%%! -pa _build/default/lib/*/ebin
+
+main(_) ->
+    Routes = [
+        {<<"POST">>, <<"/api/users">>, fun elli_openapi_demo:create_user/4},
+        {<<"GET">>, <<"/api/users/{userId}">>, fun elli_openapi_demo:get_user/4},
+        {<<"POST">>, <<"/api/echo">>, fun elli_openapi_demo:echo_text/4},
+        {<<"POST">>, <<"/api/status">>, fun elli_openapi_demo:update_status/4},
+        {<<"PUT">>, <<"/api/items/{itemId}">>, fun elli_openapi_demo:update_item/4},
+        {<<"GET">>, <<"/api/users">>, fun elli_openapi_demo:list_users/4},
+        {<<"GET">>, <<"/api/search">>, fun elli_openapi_demo:search_users/4}
+    ],
+    Port = 3000,
+    ElliOpts = [
+        {callback, elli_openapi_handler},
+        {callback_args, Routes},
+        {port, Port}
+    ],
+
+    %% Start Elli
+    case elli:start_link(ElliOpts) of
+        {ok, _Pid} ->
+            io:format(
+                "Elli openapi is started. Access the API documentation at: http://localhost:~p/swagger~n",
+                [Port]
+            );
+        {error, Reason} ->
+            io:format("Failed to start Elli server: ~p~n~n", [Reason])
+    end.
diff --git a/example/rebar.config b/example/rebar.config
new file mode 100644
index 0000000..d6532b6
--- /dev/null
+++ b/example/rebar.config
@@ -0,0 +1,10 @@
+{erl_opts, [debug_info]}.
+
+{deps, [
+    {elli_openapi, {path, ".."}}
+]}.
+
+{shell, [
+    {apps, [demo]},
+    {script_file, "demo.escript"}
+]}.
diff --git a/example/src/demo.app.src b/example/src/demo.app.src
new file mode 100644
index 0000000..e9214dc
--- /dev/null
+++ b/example/src/demo.app.src
@@ -0,0 +1,5 @@
+{application, demo, [
+    {description, "elli_openapi example application"},
+    {vsn, "0.1.0"},
+    {applications, [kernel, stdlib, elli, elli_openapi]}
+]}.
diff --git a/src/elli_openapi_demo.erl b/example/src/elli_openapi_demo.erl
similarity index 100%
rename from src/elli_openapi_demo.erl
rename to example/src/elli_openapi_demo.erl
diff --git a/src/user_handler.erl b/example/src/user_handler.erl
similarity index 100%
rename from src/user_handler.erl
rename to example/src/user_handler.erl
diff --git a/rebar.config b/rebar.config
index ca082f7..9090e27 100644
--- a/rebar.config
+++ b/rebar.config
@@ -1,13 +1,9 @@
 {erl_opts, [debug_info, warn_unused_import, warnings_as_errors]}.
 
-{shell, [
-    {apps, [elli_openapi]},
-    {script_file, "demo.escript"}
-]}.
-
 {profiles, [
     {test, [
         {erl_opts, [nowarn_missing_spec]},
+        {extra_src_dirs, ["example/src"]},
         {deps, [
             {eqwalizer_support,
                 {git_subdir, "https://github.com/whatsapp/eqwalizer.git", {branch, "main"},
@@ -22,7 +18,7 @@
 ]}.
 
 {hank, [
-    {ignore, ["test/*.erl"]}
+    {ignore, ["test/*.erl", "example/src/*.erl"]}
 ]}.
 
 {project_plugins, [erlfmt, rebar3_hank, rebar3_lint, rebar3_ex_doc, rebar3_check_app_calls]}.