awe-101 Your first AWE App

Build a small AWE application in a few minutes. This tutorial starts after the Getting Started quick path and focuses on the first useful steps: generate the app, run it, understand the generated folders, and make one tiny visible change.

Quick path

1. Generate a project from an AWE archetype.
2. Run it locally on http://localhost:18080.
3. Inspect the generated application/<your-acronym>/ resources.
4. Change one setting and restart the app.

Before you start

You need:

• Java 17 or higher
• Maven 3.x or higher
• A terminal and your preferred editor

If you have not generated a project yet, follow Getting Started first.

Step 1: Generate the application

This example uses the AngularJS archetype because it is the classic AWE starter. If you prefer React, use the same command and replace awe-boot-angular-archetype with awe-boot-react-archetype.

Use the current AWE version from Maven Central:

mvn -B archetype:generate \
 -DarchetypeGroupId=com.almis.awe \
 -DarchetypeArtifactId=awe-boot-angular-archetype \
 -DarchetypeVersion=[Archetype version] \
 -DgroupId=com.example.app \
 -DartifactId=my-app \
 -Dversion=1.0-SNAPSHOT

After the command finishes, move into the generated project:

cd my-app

Step 2: Run the application

Start the generated app:

mvn spring-boot:run

Then open:

http://localhost:18080

info

The generated application is configured with server.port=18080.

Older AWE training notes document test / test credentials for the sample test application. Treat that as version-specific guidance and verify it against the archetype version you generated before relying on it.

Step 3: Understand the generated structure

You do not need to learn the whole framework on day one. Start with these files and folders:

Path	Why it matters
pom.xml	Main Maven project file.
src/main/resources/application.properties	Application name, port, theme, database, and startup settings.
src/main/resources/application/<your-acronym>/global/	Shared AWE XML descriptors such as queries, maintain, services, and actions.
src/main/resources/application/<your-acronym>/screen/	Screen XML files. This is where UI screens live.
src/main/resources/application/<your-acronym>/menu/	Public and private navigation menus.
src/main/resources/application/<your-acronym>/locale/	Application text by language.
src/main/resources/application/<your-acronym>/profile/	Access rules and profile restrictions.

High-level rule:

• screen/ defines what users see.
• menu/ decides how users reach those screens.
• global/ contains shared backend-facing XML definitions.
• locale/ stores translatable labels.

If you want a fuller explanation later, continue with Project Structure.

Step 4: Make one tiny first customization

For the smallest safe first change, update the generated theme.

1. Open src/main/resources/application.properties.

2. Find the awe.application.theme= line. The generated value depends on the archetype:

   # Angular archetype
   awe.application.theme=sunset
   
   # React archetype
   awe.application.theme=default

3. Replace the current value with another theme name from the AWE demo theme list referenced in that same file comment.

4. Stop the app and run mvn spring-boot:run again.

5. Refresh the browser and confirm the application style changed.

This is a good first edit because it is visible, easy to revert, and helps you confirm that the generated project is now yours.

What to explore next

When you are ready for the next step, open these folders in order:

1. src/main/resources/application/<your-acronym>/menu/
2. src/main/resources/application/<your-acronym>/screen/
3. src/main/resources/application/<your-acronym>/global/

That path matches the way most AWE application work grows: navigation first, then screens, then shared logic.

Video reference

If you prefer to see the setup flow in an IDE, you can still use the original IntelliJ walkthrough video: