example-app

Example application workspace for developing and validating applications on the homelab platform.

Purpose

This repository is the reference application workspace for the homelab.

An application workspace may contain multiple independently buildable and deployable components, such as frontend applications, backend services, and workers.

Components remain in the same repository while they normally evolve as one application. They may be extracted into separate repositories when independent ownership or evolution creates a concrete reason to do so.

This repository also serves as the primary environment for experimenting with agentic application development.

Responsibilities

example-app owns:

• application source code
• application tests
• application development tooling
• application build tooling
• OCI image builds and publishing

example-app does not own:

• Kubernetes platform lifecycle
• Kubernetes desired environment state
• workload deployment manifests
• platform infrastructure

Those responsibilities belong to local-platform and local-environments.

Structure

.
├── components/
│   ├── example-backend/  # Quarkus backend service
│   └── example-frontend/ # browser application
├── docs/               # application-level documentation
└── ...

The workspace currently contains two independently buildable components:

• components/example-frontend builds the example-frontend browser application.
• components/example-backend builds the example-backend application and OCI image.

Additional application components will be introduced incrementally as concrete needs emerge.

Development

Start or reconnect to the repository development environment:

./dev.sh

Start the coding-agent environment:

./agent.sh

List available workspace tasks:

task --list

The root Taskfile.yml provides the application-workspace interface. Component specific automation remains close to each component.

Run the following commands from the workspace root. Current backend tasks include:

task backend:dev
task backend:test
task backend:verify
task backend:image:build

Run the following commands from the workspace root. Current frontend tasks include:

task frontend:dev
task frontend:test
task frontend:verify
task frontend:build
task frontend:image:build

Each component can also be operated directly from its own directory using its Taskfile.yml: components/example-backend and components/example-frontend.

The backend currently publishes the example-backend OCI image. Source layout and deployment identity are intentionally separate concerns.

Versioning

example-app is versioned as one application workspace.

All components in the repository share the same Git-derived application version. A Git tag therefore represents the version of the complete application workspace at that commit, even though its components remain independently buildable and deployable.

Release tags use the form:

<version>

For example:

0.6.1

Published component artifacts use the application version as their artifact version. With multiple components in the workspace, a single application release may therefore produce artifacts such as:

example-backend:0.6.1
example-frontend:0.6.1

Development builds may include the Git commit identifier and dirty-worktree state in their version so that an artifact can be traced back to the exact workspace state from which it was built.

Set the shared component version from the workspace root:

task version:set VERSION=0.8.0

This updates the backend Maven revision and frontend npm metadata, then displays the declared values. Confirm they match at any time with:

task version:check

Release tags remain developer-controlled. The release workflow is: set the version, review the diff, verify components, commit, tag the release, then release images.

A component that requires an independent version or release lifecycle is a signal that it may no longer belong to the same cohesive application workspace and should be considered for extraction into a separate repository.

Architecture

The application workspace model is defined by ADR-0007 in the homelab repository.

Deployment boundaries do not automatically imply repository boundaries.