# Lab 7: Build a full web app from three models

A Library web application with tables, a bar chart and a chatbot, generated from a class diagram, a GUI model and an agent model, and running locally with Docker Compose.

| Time | Level | Runs with | Do first | Track |
| --- | --- | --- | --- | --- |
| 1 h 15 min | Intermediate | Browser, Docker | [Lab 1](https://labs.besser-pearl.org/labs/first-model/) | Full applications |

**You'll learn to**

- Combine a class diagram, an agent diagram and a GUI model in one project
- Generate a GUI from a class diagram and extend it with a chart and a chatbot widget
- Generate the full web application and run it with Docker Compose
- Fill the database through the generated REST API and see the data in the frontend

**You'll need**

- A modern browser
- Docker Desktop (or Docker Engine with the Compose plugin), running
- About 5 GB of free disk space for the three images
- A tool to unzip files

**Files for this lab**

- [Finished Library App project (JSON)](https://labs.besser-pearl.org/files/web-app/library-app.json)

Online version: https://labs.besser-pearl.org/labs/web-app/

---

A web application needs at least three things: the data it manages, the screens people use, and often an
assistant that answers questions. In BESSER each of these is a separate model in the same project: a class
diagram, a GUI model and an agent diagram. The Web Application generator reads all three and produces a
FastAPI backend, a React frontend, one service per agent and a `docker-compose.yml` that starts everything.

In this lab you build a small Library application. You reuse two templates so the result is predictable,
design the screens in the no-code GUI editor, generate the code, run it with Docker and fill it with data.

## 1. Create a Full Web Application project

1. Open [editor.besser-pearl.org](https://editor.besser-pearl.org/) and open **File > New Project**
   (on a first visit, click **Start modelling** on the **Model it** card).
2. Name the project `Library App`, keep **Low-code**, and choose the modeling perspective
   **Full Web Application**. Click **Create Project**.

![Create A Project form with the name Library App, the Low-code view and the Full Web Application perspective](https://labs.besser-pearl.org/labs/web-app/new-project-full-web-app.png "The Full Web Application perspective shows exactly the three diagram types this lab needs")

3. Load the data model: **File > Load Template**, category **Class Diagram**, template **Library**,
   then **Load Template**. Click **Quality Check**; it reports "Diagram is valid".

> **Check your work**
>
> The sidebar lists **Class**, **Agent** and **GUI**. The Class editor shows Book, Author, Library and
> the Genre enumeration.

## 2. Add the Greeting Agent

1. Click **Agent** in the sidebar.
2. Open **File > Load Template**, choose the category **Agent Diagram** and the template
   **Greeting Agent**, then click **Load Template**.
3. Click **Quality Check**. It reports "Diagram is valid".

![Greeting Agent state machine: initial, greeting, good and bad states connected by intents and Auto transitions](https://labs.besser-pearl.org/labs/web-app/greeting-agent.png "Each state has fixed text replies; intents decide which transition fires")

Read the model before you continue. The agent waits in `initial`. When the user's message matches
`greeting_intent` (training sentences such as "Hi", "Hello", "Howdy") it moves to `greeting`, which replies
"Hi" and "How are you?". The answer is classified as `good_intent` or `bad_intent`, the matching state
replies, and an **Auto** transition returns to `initial`. No language model is involved, so the agent needs
no API key.

> **Check your work**
>
> The Agent editor shows four states (`initial`, `greeting`, `good`, `bad`), three intent transitions and two
> **Auto** transitions back to `initial`.

## 3. Generate the GUI from the class diagram

1. Click **GUI** in the sidebar. The page builder opens with an empty canvas. The **REFERENCES** bar shows
   that this GUI uses the class diagram `Library`.

![Empty GUI editor with the device icons and the magic-wand button on the left of the toolbar](https://labs.besser-pearl.org/labs/web-app/gui-editor-empty.png "The magic wand next to the desktop, tablet and phone icons generates a GUI")

2. Click the magic-wand button, **Auto-Generate GUI from Class Diagram**.
3. The dialog warns that it will clear the current GUI and lists what it creates. Click **Generate GUI**.

![Auto-Generate GUI from Class Diagram dialog listing a navigation panel, a page per class and method buttons](https://labs.besser-pearl.org/labs/web-app/auto-generate-gui-dialog.png "Auto-generation replaces the whole GUI, so run it before you customise anything")

4. Open the **Pages** panel (the right-most icon in the panel toolbar) and click the **Book** page.

![Generated Book page with a navigation sidebar, the Book List table, an Add Book button and a decrease_stock button](https://labs.besser-pearl.org/labs/web-app/gui-autogenerated-book-page.png "One page per class, each with a data table bound to that class and buttons for its methods")

> **Before you continue**
>
> **Auto-Generate GUI from Class Diagram** cannot be undone and removes everything you added by hand,
> including chatbot widgets. Run it first, then customise.

> **Check your work**
>
> The **Pages** panel lists Book (`/book`), Library (`/library`) and Author (`/author`). The Book page shows a
> table with the columns Title, Pages, Stock, Price, Release, Genre, Library and Authors.

## 4. Add a bar chart and the chatbot widget

The table already exists. Add a chart of book prices and the Greeting Agent as a chat window on the Book page.

1. Open the **Open Blocks** panel (the plus icon in the panel toolbar). Drag **Bar Chart** from the
   **Basic** group onto the Book page, below the **decrease_stock** button.
2. Click the chart to select it. The **Component settings** panel opens. Set:
   - **Chart Title**: `Book prices`
   - Under **Chart Series** > **Series 1**: **Data Source** `Book`, **Label Field** `title`, **Data Field** `price`

![Bar chart selected on the Book page with Chart Title Book prices and a series bound to Book, title and price](https://labs.besser-pearl.org/labs/web-app/gui-bar-chart-settings.png "The preview shows sample bars; the generated app plots the real records")

3. Open **Open Blocks** again and drag **BESSER Agent** onto the Book page, above the Book List table.
4. Click the widget. In **Component settings**, choose `Greeting Agent` in the **Agent** field and set
   **Agent Title** to `Library assistant`.

![BESSER Agent widget titled Library assistant with Greeting Agent chosen in the Agent field](https://labs.besser-pearl.org/labs/web-app/gui-agent-widget-settings.png "Choose the agent explicitly; the widget stores its name and the generated app connects to that agent")

> **Note**
>
> The editor saves the GUI automatically; the status at the bottom right changes to "Saved". Charts and tables
> show placeholder data in the editor because the database does not exist yet.

> **If something goes wrong**
>
> If a block does not land on the page, drop it onto an existing element such as the table or the button: the
> blue outline shows where it will be inserted. Use the arrow and move icons on the selected element's toolbar
> to change its position afterwards.

> **Check your work**
>
> The Book page contains, from top to bottom, the Library assistant chat window, the Book List table, the
> **decrease_stock** button and the Book prices chart.

## 5. Generate the web application

1. With the GUI editor open, choose **Generate > Web Application**. (From the class diagram, the same
   generator is under **Generate > Web > Web Application**.)
2. The **Web Application Generator** dialog lists the diagrams it will use. Check that both required
   diagrams have a green tick, then click **Generate**.

![Web Application Generator dialog with the Library class diagram and the GUI diagram ticked and one agent diagram available](https://labs.besser-pearl.org/labs/web-app/web-app-generator-dialog.png "Agent diagrams are optional and are included through the widgets that reference them")

3. The browser downloads `web_app_output.zip`. The zip has no top-level folder, so create a folder
   `library_app/` and extract it there. You get:

```text
library_app/
├── docker-compose.yml
├── BESSER_GENERATION.md
├── backend/          FastAPI app: main_api.py, routers/, sql_alchemy.py, pydantic_classes.py, Dockerfile
├── frontend/         React + TypeScript (Vite): src/pages/Book.tsx, Library.tsx, Author.tsx, Dockerfile
└── agents/
    └── greeting_agent/   Greeting_Agent.py, config.yaml, Dockerfile
```

Open `frontend/src/pages/Book.tsx`. Your GUI model is now code: you find
`<AgentComponent ... agent-name="Greeting Agent" agent-title="Library assistant" />` and a
`<ChartBlock ... chartType="bar-chart" title="Book prices" ...>`.

> **If something goes wrong**
>
> "Cannot generate web application: GUI diagram is empty." means the GUI model has no pages. The dialog warns
> about it with "(empty - will be skipped)". Go back to the GUI editor and run
> **Auto-Generate GUI from Class Diagram** first.

> **Check your work**
>
> `library_app/` contains `docker-compose.yml` and the folders `backend`, `frontend` and `agents/greeting_agent`.

## 6. Run the application with Docker Compose

`docker-compose.yml` defines three services: `frontend` on port 3000, `backend` on port 8000 with a SQLite
database in the volume `sqlite_data`, and `greeting_agent_agent` with its WebSocket on port 8765 (and 5000).

1. Make sure ports 3000, 8000, 8765 and 5000 are free, then start everything from `library_app/`:

```bash
docker compose up --build
```

The first build downloads Python, Node and PyTorch layers and takes several minutes (about 7 minutes on a
fast connection; the agent image alone is about 3 GB). It is ready when the log shows these three lines:

```text
backend-1               | INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
greeting_agent_agent-1  | ... Greeting_Agent's WebSocketPlatform starting at ws://0.0.0.0:8765
frontend-1              |  INFO  Accepting connections at http://localhost:3000
```

The agent also logs an error about the monitoring database (`could not translate host name "YOUR-DB-HOST"`).
Monitoring is optional and the agent works without it.

2. Open [http://localhost:3000](http://localhost:3000). The app opens on the Book page. The table and the
   chart are empty because the database is empty.
3. Type `Hello` in the chat window and press <kbd>Enter</kbd>, then answer `Fine`.

![Running app with the Library assistant chat: Hello, Hi, How are you?, Fine, I am glad to hear that!](https://labs.besser-pearl.org/labs/web-app/app-agent-chat.png "The status turns to Connected when the frontend reaches the agent's WebSocket")

> **If something goes wrong**
>
> If `pip install` or `npm install` fails during the build with `CERTIFICATE_VERIFY_FAILED` or
> `self-signed certificate in certificate chain`, your network inspects HTTPS traffic and the containers do
> not trust its certificate. Build on another network, or ask your IT department how to add their certificate
> to Docker builds. If a port is already in use, stop the other program or change the left-hand port numbers
> in `docker-compose.yml`.

> **Check your work**
>
> `docker compose ps` lists three running services, http://localhost:3000 shows the Book page, and the chat
> header says "Connected".

## 7. Fill the database through Swagger and see it in the app

The backend is the same kind of FastAPI service you would get from **Generate > Web > Full Backend**, with
interactive documentation at [http://localhost:8000/docs](http://localhost:8000/docs).

1. In Swagger, expand **POST /library/**, click **Try it out**, and execute:

```json
{
  "name": "City Library",
  "address": "1 Main Street",
  "telephone": "+352 123 456",
  "web_page": "https://library.example.org"
}
```

2. Create an author with **POST /author/**:

```json
{
  "name": "Ada Writer",
  "birth": "1970-05-01"
}
```

3. Create three books with **POST /book/**, changing `title`, `price` and `genre` each time. In the
   Library template a book can belong to several libraries, so `library` is a list here:

```json
{
  "title": "Modeling 101",
  "pages": 240,
  "stock": 5,
  "price": 29.9,
  "release": "2024-03-15",
  "genre": "Technology",
  "library": [1],
  "authors": [1]
}
```

The other two books used in the screenshot are `Patterns in Practice` (42.5, Technology) and
`Night Train` (12.0, Thriller). Remember that the OCL constraint requires more than 10 pages.

4. Reload http://localhost:3000. The Book List shows the three books with their library and author, and the
   Book prices chart draws one bar per book.

![Running app: Book List with three books and the Book prices bar chart](https://labs.besser-pearl.org/labs/web-app/app-book-table-chart.png "Table rows and chart bars come from GET requests to the backend")

5. Try the generated frontend as a user: open the Author page, click **Add Author**, fill in Name and Birth
   and submit. The form also offers the existing books as relationships. The pencil and bin icons in each row
   edit and delete records without Swagger.

When you are done, press <kbd>Ctrl+C</kbd> in the terminal and run `docker compose down`. Add `-v`
(`docker compose down -v`) only if you also want to delete the database volume.

> **Check your work**
>
> The Book page lists three books, the chart has three bars, and the Library page shows City Library with
> its books.

## 8. Exercise: a digital twin dashboard

> **Exercise: Model and run a digital twin application**
>
> Build a new project for a digital twin. Model `PhysicalThing` (`name`, `location`), `DigitalTwin` (`status`,
> `lastSync`), `Sensor` (`type`, `unit`) and `Measurement` (`timestamp`, `value: float`). A physical thing has
> zero or more sensors and digital twins; a sensor produces many measurements. Auto-generate the GUI, then add
> a line chart of measurement values over time on the Measurement page. Generate the application, run it, and
> fill it through Swagger in the right order so every mandatory association end has a target.

<details>
<summary>Show a solution</summary>

Decide the multiplicities first: `1` on the PhysicalThing end and `0..*` on the Sensor end means every
sensor needs an existing physical thing when you create it. For the line chart, use `timestamp` as the label
field and `value` as the data field.

</details>

> **Exercise: Replace the Greeting Agent with your own assistant**
>
> Create an agent with an initial state and at least six states that each reply with a fixed text: what a
> digital twin is, how sensors work, how to read a measurement, help, back and exit. Give the states a
> fallback body that answers messages matching no intent. Put the agent on the dashboard page with the
> **BESSER Agent** block and regenerate.

<details>
<summary>Show a solution</summary>

Start from the Greeting Agent structure: one hub state that every answer state returns to with an
**Auto** transition. Intent names must differ from state names, so use names like `sensor_intent`.

</details>

---

Checked against BESSER 8.0 on 2026-10-02.
