BonAppetit Reference Documentation

This project is being refactored, modernized and moved to github. Unfortunately it is far from usable at the moment. More stuff coming soon. Stay tuned.

This is the reference documentation of the BonAppetit @ GitHub project.

1. Introduction

BonAppetit is a free Point-of-Sale solution for small and medium restaurants. It consists of an Android client and a Java server application connected to a receipt printer.

The client app provides the ability to record, edit and delete orders for menu items configured in the server. Orders are transferred to the server via WLAN.

The server saves the recorded orders to a database and prints receipts using a thermal receipt printer. The receipts contain all information required to further process the order consisting of table number, item name, options, additional free text notes as well as the service member who took the order and the time the order was registered.

2. Operations

In this section you will find all you need to know to operate BonAppetit.

2.1. Dependencies

The BonAppetit server requires

Java SE Runtime Environment 8 or higher.
A SQL database.
A directory in the file system where log files are stored. Referred to as BONAPPETIT_BASE, see Configuration.
An external properties file where you specify your database and other settings, see External Configuration.

2.2. Configuration

2.2.1. Base Directory (aka BONAPPETIT_BASE)

The BonAppetit Server requires a directory referred to as BONAPPETIT_BASE. This is the location where the server writes its log files.

The BONAPPETIT_BASE directory has the following layout

BONAPPETIT_BASE

The BONAPPETIT_BASE root directory.

log: All log files generated by the BonAppetit Server are written to this directory. The log file is rotated as soon as its size reaches 10MiB.

2.2.2. Authentication and Authorization

All server endpoints are secured via basic auth. Username and password are expected in form of an authorization header in all requests to the server (see Basic Auth @ Wikipedia).

2.2.3. External Configuration

The main external configuration is read from bonappetit.properties. Its location must be handed to the jar on startup (see JVM Parameters). The BonAppetit Server project is a Spring Boot application. Therefore the bonappetit.properties file can be used to provide or override any common Spring Boot application property that can be used in the standard application.properties.

The following properties consisting of standard spring boot as well as of bonappetit specific properties are especially important:

Table 1. External configuration via bonappetit.properties
Name	Required	Description	Default	Example
security.admin.username	true	The username of the admin user. This is the only user that is authorized to manage API users via the `/api/users` REST endpoints.	-	admin
security.admin.passwordHash	true	The salted password hash of the admin user (see `security.admin.username`). Must be computed using the open source library Heimdall	-	1:1:unf6gJNOOlayrKyEQgfEk7 K4RvwhW9WI:i=4e20:gH613KUcJ OtL1UcPUadsVvAUoUfvPBoS
spring.datasource.url	false	The URL of the database where all data (staff members, orders, etc.) is stored. Per default the server is configured to use a MySQL database with a schema named `bonappetit` running at `localhost:3306`.	jdbc:mysql://localhost/bonappetit	jdbc:mysql://localhost/bonappetit, jdbc:mysql://localhost/my-restaurant
spring.datasource.username	false	The database user that is used to access the database	bonappetit	bonappetit,peter
spring.datasource.password	true	The password to use to authenticate `spring.datasource.username` against the database.	-	s3cr3t
flyway.enabled	false	Whether flyway migration is performed on server startup. Warning: do not enable this option when working with a production database. Instead: Do a dry run of the migration on a copy of your production database (Production databases always contains surprises). Then apply the migration manually to the production database.	false (profile PROD), true (profile LOCAL), see Profiles	true, false
printing.printService.name	true	The name to use when looking up the `javax.print.PrintService` to use. This is usually the display name of the printer.	-	CITIZEN CT-S310II
printing.timeZone.id	true	The timezone id to use for formatting dates when printing. Internally all dates are processed in UTC.	-	Europe/Berlin
printing.options.emphasised	false	Comma separated list of the titles of the options or radio items which should be printed in an emphasised way. At the moment to emphasize an option means to print it big and bold next to the item title. E.g. if you configure an item with the title "Pizza" and a Radio-Option with title "sort" and two radio items with the titles "Hawaii" and "Capricciosa" you can set this property to "Hawaii,Capricciosa" to make the printer print "Pizza Hawaii" as item title instead of printing "Pizza" as item title and "Hawaii" as standard option below the title.	-	small,Hawaii,light
printing.options.notPrinted	false	Comma separated list of the titles of the options or radio items which should not be printed at all. Some options like size have to be selectable when taking an order but they do not have to be printed. E.g. the default for the size of a drink might be "big" so we don’t hve to print it.	-	big

2.2.4. Profiles

Profiles control what configuration the BonAppetit Server is run in (Specified on startup via JVM Parameters).

Table Profiles lists the existing profiles.

Table 2. Profiles
Name	Description
PROD	Configures the BonAppetit Server for production use. Automatic database migration on startup is disabled.
LOCAL	Configures the BonAppetit Server for local use. Automatic database migration on startup is enabled.

See JVM Parameters to learn how you select the profile.

2.2.5. JVM Parameters

Table JVM parameters lists the JVM parameters that are supported by the BonAppetit-Server. Note that you have to prefix them with -D when running from the command-line.

Table 3. JVM parameters
Name	Required	Description	Default	Example
BONAPPETIT_BASE	true	The path of the base directory where logs are stored.	-	"M:\bonappetit-base", "BONAPPETIT_BASE", ".", "/home/peter/bonappetit-base"
spring.profiles.active	true	The profiles to activate. Profiles control the server configuration, e.g. the database URL and credentials. PROD means the server is run in production configuration. LOCAL is only relevant to developers working with a database that contains only test data.	-	PROD, LOCAL
spring.config.location	true	The location of the bonappetit.properties file. Due to spring boot internals this has to be defined via program argument explicitly.	-	"M:\BONAPPETIT_BASE\config\bonappetit.properties"

3. Development Management

3.1. Domain Model

TBA

3.2. Use Cases

Table 4. Staff Member Use Cases
ID	Description	Benefit (so that…)
S-US-1	As a client i want to be able to query the staff members that work at the restaurant.	so that i can provide a select box in the app.
S-US-2	As a staff member i want to be able to select a staff member name in the app	so that my orders can be related to me.

4. Architecture Documentation

4.1. Implementation Architecture (I-Architecture)

4.1.1. BonAppetit Server

The following illustration shows the canonical package structure of a business component for the example "Foo"-component.

foo

The top level package is named after the component. It contains the public API interface, parameter and exception types of the component.

api

The api package contains all parts of the public API of the business module (interfaces, exceptions, dtos)

to: The transport objects (DTOs) that the component hands to the caller.

impl

The impl package contains the implementations of the top level api interfaces.

impl: The production impls of the top level api interfaces.
mock: Contains mock implementations of the top level api interfaces that.

entity

The entities package contains the entity types which are mapped to the database.

dao

The data access objects package contains the data access layer api interfaces.

impl: The real impl of the daos.
mock: A mocked impl of the daos that provide test data.

The packages api and api.dto are part of a separate module to be reusable in client code (as jar).

4.1.2. BonAppetit Android App

Layout Style Guide

The following guidelines are partly based on the following articles:

https://github.com/futurice/android-best-practices

Layout XML vs. Style

Keep only layout (positioning, margin, sizing) and content attributes in the layout files, while keeping all appearance details (colors, padding, font) in styles files.

Attributes that are defined in the layout XML:

android:id
android:layout_**
android:orientation for a LinearLayout
android:text
android:layout_width and android:layout_height

Other android:** should stay in a style XML

Attribute Order and format

One attribute per line
android:id as the first attribute always
android:id is only present if required to reference the view
android:layout_** attributes at the top
style attribute at the bottom
Tag closer /> on its own line, to facilitate ordering and adding attributes.

<ListView
            android:id="@+id/staffMembersListView"(1)
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            style="@style/MyListView.SpecialStyle"(2)
            />

1	`android:id` attribute in camelCase
2	`style` attribute in PascalCase