Shearora

1What this is

27 screens 12 painters 3 dependencies 0 image assets

Shearora is a customer-facing booking app for a single shop. Not a marketplace: the stylists, the services, the opening hours and the walk-in queue all belong to one salon, which is the shop that publishes the app. That single choice is why there is no map SDK, no commission split and no "find salons near me" anywhere in the project, and it is also why the walk-in queue can exist at all. A marketplace has nobody to queue for.

It is built around four things a real shop does that a booking calendar cannot express: fitting a cut into the gap that is actually there, writing down the guard numbers so nobody has to describe them again, running a walk-in line alongside the book, and knowing that a haircut has a shelf life. Chapter 4 covers all four.

What comes in the download

2Get it running

You need the Flutter SDK, version 3.29 or newer, and either Xcode or Android Studio. Nothing else: there is no key to obtain, no account to make and no server to stand up first.

From a terminal

Unzip the download, then from inside the app folder:

flutter pub get
flutter run

The app opens on its splash screen, walks itself to a three-page introduction, and lands on a sign-in form that is already filled in. Tap Sign in. With no server configured nothing is checked and nothing is sent anywhere, which the line under the form says in as many words.

Without a terminal

1. Open Android Studio or VS Code.
2. File → Open, and choose the shearora_ui_kit folder from the unzipped download. Open the folder itself, not the zip and not the folder above it.
3. Wait for the editor to finish fetching packages. Android Studio does this on its own; VS Code offers a Get packages prompt at the bottom right.
4. Pick a device or simulator from the toolbar, then press Run.

If the run button is greyed out, the editor has not finished indexing yet. Give it a minute; the Dart plugin reports when it is ready.

3Every screen

Twenty-seven screens, and this is all of them. Some appear more than once below because a screen with a sheet open, or scrolled, or in the dark theme, is a state you will need to look at while you are working.

How they are grouped

Outside the tabs: splash, three introduction pages, sign-in, create account and the six-digit code screen. Three bottom sheets — the service picker, the cut-card picker and the cancel confirmation — each get their own frame in the walk-through.

4The four signature screens

These are the four that are not in any other booking template, and the reason the project is laid out the way it is. Each one is drawn in code and driven by a plain Dart engine you can read in a sitting (chapter 9).

The time rail

A twelve-hour day squeezed onto a phone gives a forty-five minute cut about twenty pixels, which is too small to grab and too small to read. So the rail shows one four-hour window at a time, and the control that picks the window also tells you how many openings each one has.

Guard dials and the cut card

Save the four numbers as a cut card and the barber has them before you sit down. It is also what makes the fourth screen possible: you cannot say when a fade has grown out unless you know it was a fade.

The walk-in queue

The regrowth strip

5Logo and colors

One file drives every color in the app: lib/app/core/theme/app_colors.dart. Change the brand values there and the screens, the launcher icon and the bundled landing page all follow, because none of them is a picture.

The brand red is three values, not one

One hex cannot do two jobs. White text needs a fill dark enough to sit on; a store thumbnail needs to be bright enough to be seen on a shelf of other thumbnails. Those two ranges do not overlap, so the red is graded:

Pick by asking what sits on top of the color, not by which red looks nicer: text on it wants primary, text of it wants primaryDeep, and nothing on it at all wants primaryBright.

The launcher icon and the store tile

The mark is a barber pole, drawn by assets/icon/make_icon.py rather than exported from a design file. If you only want to recolor it, change the three color constants at the top of that script and run:

python3 assets/icon/make_icon.py
dart run flutter_launcher_icons

That writes the 1024px icon, the Android adaptive layer, the favicon, the web icons and an 80×80 store tile in one pass. Python needs Pillow (pip install pillow).

Replacing the icon with your own, step by step

You do not need Python for this, and you do not need to read the flutter_launcher_icons documentation. The configuration is already in pubspec.yaml under flutter_launcher_icons:; you only supply two pictures.

1. Export your icon as a PNG, exactly 1024×1024 pixels, square, with no rounded corners and no transparency. Both stores round the corners themselves; a pre-rounded or transparent icon shows a black or white frame. Save it over assets/icon/app_icon.png.
2. Export a second PNG, also 1024×1024, this time with a transparent background, containing only the mark. Keep the mark inside the central two thirds of the canvas (roughly a 680×680 square in the middle): Android crops adaptive icons to a circle, a squircle or a rounded square depending on the phone, and anything near the edge is cut off. Save it over assets/icon/app_icon_foreground.png.
3. Open pubspec.yaml and set adaptive_icon_background to the hex color that should sit behind the mark on Android. It is "#C8202F" today.
4. From the shearora_ui_kit folder run dart run flutter_launcher_icons. It writes every size the two platforms want: android/app/src/main/res/mipmap-mdpi through mipmap-xxxhdpi (48 to 192 px), the drawable-*/ic_launcher_foreground.png layers, and the 21 files in ios/Runner/Assets.xcassets/AppIcon.appiconset including the 1024 px App Store icon. remove_alpha_ios: true in the same block strips transparency from the iOS set for you, because App Store Connect rejects an icon with an alpha channel.
5. Uninstall the app from the device or simulator and install it again. Launchers cache icons; a hot restart will keep showing the old one and make you think the step failed.
6. The web icons are separate: replace web/favicon.png (16×16) and web/icons/Icon-192.png, Icon-512.png, Icon-maskable-192.png, Icon-maskable-512.png by hand, or let make_icon.py derive them if you kept the script.

6Changing the app name and the bundle ID

Three things carry a name: what shows under the icon, the identifier the stores key off, and the Dart package name. They are set in different places and none of them changes the others.

The name under the icon

The bundle identifier

The Dart package name is shearora_ui_kit, set by the name: line in pubspec.yaml. Changing it means changing every package:shearora_ui_kit/... import in the tests, so it is the one rename worth leaving alone unless you have a reason.

7Fonts

Three typefaces ship inside the app, in assets/fonts/:

Nothing is downloaded at runtime, so the app renders identically offline and on first launch. All three are under the SIL Open Font License 1.1 and the full text is in assets/fonts/LICENSES.txt.

Chivo and Libre Franklin are published upstream as variable fonts; the files here are static instances cut at the weights the app uses. That keeps the file names free of the square brackets a variable font carries, which a web build percent-encodes and some marketplaces reject.

Swapping one

1. Drop your .ttf into assets/fonts/.
2. Update the fonts: block in pubspec.yaml.
3. Change the family name in lib/app/core/theme/app_text_theme.dart. That is the only file in the project that names a font.

8Where the data comes from

Every screen talks to one interface, lib/app/data/services/repository.dart. Out of the box it is backed by MockRepository, which answers from a file of written values. Pass a base URL and ApiRepository takes over with no change to any screen.

The sample data is written down, not generated

lib/app/data/mock/mock_data.dart holds one shop, six barbers, fourteen services, twelve bookings, three cut cards, one live queue ticket and six reviews. Nothing in it reads the system clock or a random number generator: today is a constant, Monday 14 September 2026 at 10:20.

That is not tidiness. The screenshots, the driver walk-through, the figures in this document and the bundled landing page all have to agree with each other months apart, and they can only do that if "today" is a fixed point. Change that one value and every relative label in the app moves at once, which is also the quickest way to see that none of them is hard-coded prose.

Replacing it with your own API

Rewrite api_repository.dart and nothing else. It is one file of HTTP calls returning the same models the screens already take. The wire format it expects is Laravel's default API resource shape — {"data": [...]} for a collection — because that is what the included back end emits.

9The four engines

The arithmetic behind the four signature screens lives in lib/app/core/engines/. Each file is plain Dart: no Flutter import, no clock of its own, no I/O. They are the most reusable thing in the project and the easiest to change without breaking a screen.

All four are covered directly in test/, edges included: an empty day, a full one, a gap that is one minute too small, a queue of zero, a guard below the bottom of the ladder, a hold of zero days. That is where to start if you are changing how any of them behaves.

10Errors and empty states

Every list in the app has three states drawn: loading, empty, and something went wrong. They are reachable in the demo — the sample repository answers on a deliberate 260ms delay so the skeleton loaders are visible rather than theoretical.

11What the admin does

backend/ is a Laravel 13 application with a Filament 5 admin panel and a token-authenticated REST API. It manages seven kinds of record:

The first three are catalog rows: the panel edits them and the app reads them. The last four belong to whoever signed in, and the API refuses to hand one person another person's rows.

Credentials the seeder creates

Change both before anything of yours is on the internet. They exist so the panel opens the first time, and for no other reason.

12Putting the back end online

A note on notation for the rest of this chapter: anything written in <angle brackets> is a value of yours — your domain, your database name, the folder your host gave you. Nothing in angle brackets is meant to be typed literally, and no path in these steps is a real directory on your server until you make it one.

A. With Docker, on your own machine

One command, and it brings its own database:

docker compose up -d

The panel is then at http://localhost:8000/admin. To wipe everything and start again from an empty database, see chapter 15 — the command that does it has no confirmation step.

B. With a terminal, on a server

./install.sh

The script checks your PHP version, installs the dependencies, writes an .env, generates an application key, creates the database tables, seeds the sample shop and tells you the URL. If anything is missing it stops and says what, rather than half-installing.

C. On shared hosting, without a terminal

1. In your host's control panel, set the PHP version for the domain to 8.4 or newer.
2. Create a MySQL database and a user, and note the name, user and password.
3. Upload the whole backend/ folder over FTP, outside your public folder if the host allows it.
4. Point the domain's document root at backend/public. This is the step people miss, and skipping it exposes your .env to the internet.
5. Copy .env.example to .env using the file manager, and fill in the three database values from step 2.
6. Still in the control panel, find Terminal or Cron Jobs and run php artisan key:generate once, then php artisan migrate --seed once.
7. Open https://yourdomain/admin and sign in with the admin credentials from chapter 11. Change them immediately.

HTTP or HTTPS: what the phone will and will not connect to

The app talks to the address you give it in chapter 13. Both mobile platforms treat a plain http:// address as unsafe by default, and each refuses it in its own way, so read this before the first “cannot reach the server” message.

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsLocalNetworking</key>
  <true/>
</dict>

Production is HTTPS, full stop. Point the app at https://<your-domain> and have a valid certificate on the server. On shared hosting that is usually a checkbox called AutoSSL or Let's Encrypt in the control panel; on your own server, certbot does it in one command and renews it for you. With HTTPS in place you need none of the exceptions above, and you should remove any you added while testing before you build for the stores (chapter 22). Two more things the phone needs from the server: the certificate must match the host name you typed (a certificate for www.example.com does not cover api.example.com), and it must be issued by a public authority — a self-signed certificate is refused by both platforms exactly like plain HTTP is.

Day-to-day, without the command line

You do not need a terminal to run this once it is up. Everything below is a control panel job:

13Connecting the app to it

Two ways, and they do exactly the same thing. Use whichever fits how you build.

A. At build time, from the command line

flutter run --dart-define=API_BASE_URL=http://127.0.0.1:8000

Use your machine's LAN address rather than 127.0.0.1 when you are running on a physical phone: the phone's own loopback is not your computer.

B. By editing one line

If you build from Android Studio or VS Code and would rather not pass flags, open lib/app/data/services/app_binding.dart and change this:

static const String apiBaseUrl = String.fromEnvironment('API_BASE_URL');

to this:

static const String apiBaseUrl = 'http://127.0.0.1:8000';

That is the whole change. Everything downstream — which repository gets built, whether the app waits for a token, what the settings screen reports — reads from that one constant.

What happens then

The sign-in form stops being a formality. It posts to POST /api/auth/login, keeps the token it gets back for the session, and every later request carries it. A wrong password comes back as a line of text under the button rather than as a crash.

Authentication headers

Every request the app makes to the back end carries three headers. They are built in one place, ApiRepository._headers, so changing how your server expects to be addressed is a change to a single getter.

The token comes from POST /api/auth/login, which Sanctum issues as a personal access token. A build can also be handed one directly with --dart-define=API_TOKEN=…, which is useful for a demo device that should open already signed in.

If your own back end authenticates differently — an API key header, a cookie session, OAuth — rewrite the getter and nothing above it changes. No screen, controller or service in this app constructs a header.

14Landing page

It is a product website for your app, not for this item. Put it on any static host, or drop it in the back end's public/ folder and it serves itself.

Three places are marked <!-- replace --> in the HTML: the two store links, the contact address and the privacy and terms links. Everything else is ordinary copy you can rewrite. The colors and the two typefaces come from the app, so re-skinning the app re-skins this too — the page is regenerated by tools/make_landing.py in the workspace this was built in, but you do not need that: it is a single HTML file you can edit directly.

15Commands

Everything you are likely to type, in one place, with what it does to your data.

The app

The back end

Regenerating what is in this folder

16Tests and quality

138 Flutter tests 50 backend tests 157 backend assertions 0 analyzer issues

The Flutter tests are in test/ and fall into four groups:

• The engines. Every rule and every edge, including the ones that only bite once: a gap one minute too small, a tie between two legal start times, a queue of zero, a hold of zero days.
• The painters. Each drawn widget is built the way a screen builds it and then measured. A CustomPaint with no child collapses to zero on whichever axis its parent leaves loose, and a screen that renders nothing passes the analyzer, the tests and the driver walk-through without complaint. These are the check that catches it.
• The booking screen. Driven through its controller, then inspected: is the chip for the chosen day actually the filled one?
• The app itself. It boots, walks its own introduction, signs in with the credentials it arrives holding, and lands on a populated home screen.

integration_test/ holds three more: the screenshot walk-through, and the two recordings that produced the animations in chapter 4. They are driven through controllers rather than synthetic taps, because a synthetic pointer paints a test cursor into the recording.

17Troubleshooting

The app

The back end

18Glossary

19Third-party code and licenses

Flutter packages

Three, deliberately. Fewer dependencies means a wider range of Flutter versions this will compile against, which matters more to you than any one convenience package would.

Typefaces

Chivo, Libre Franklin and Alumni Sans Pinstripe, all SIL Open Font License 1.1. Full text in assets/fonts/LICENSES.txt.

Back end

Laravel (MIT), Filament (MIT), Laravel Sanctum (MIT), Pest (MIT). Their own license files are under backend/vendor/ once you install.

Images

There are none. assets/ contains fonts and the generated icon, and nothing else — every card, pole, dial, rail and head in the app is drawn in code. Nothing in this item is an AI-generated image, a stock photo or a licensed illustration, because there are no images to be any of those.

20What is not included

Stated plainly so you can decide before you build on it.

• No payment processing. Prices are shown and bookings are made; money changes hands in the shop. There is no card form, no deposit and no tip flow anywhere in the project.
• No push notifications. The reminder switches in settings are wired end to end but there is no push service behind them. Connecting one is yours.
• No SMS. The six-digit code screen accepts any six digits and sends no message.
• No maps or location. A single shop has one address, and it is text.
• No staff-facing app. The admin panel is the shop's side; there is no second Flutter application for barbers.
• No design source files. The interface is defined in Dart, not in Figma or Sketch. The color file and the text theme are the design system.
• No multi-shop mode. Adding one means changing the data model and removing the queue, which is most of the project.

Connecting this to a live back end, a push service or any other third-party platform will involve those services, which will incur their own separate costs and are not part of this item. Hosting for the included Laravel application is yours to arrange.

21Support and license

Questions about getting it running, re-skinning it, or connecting the back end are answered through the item's comments on the marketplace page. Item support covers this template: the code in the download and the instructions in this file.

It does not cover your hosting account, your marketplace developer account, or a third-party service you connect the app to. Those have their own support, and they will know their own product better than anyone here.

License

Whichever license you bought on the marketplace. In short: a Regular License covers one end product that is free for its users; an Extended License covers one end product that users are charged for. One license per end product either way, and the marketplace's own license page is the authority, not this paragraph.

22Building for release and the stores

Everything up to here runs from a terminal or an IDE. Putting the app in buyers' hands means a signed release build and two store consoles, and both have requirements that are easier to meet before you start than to discover from a rejection. This chapter is the order of operations; the bundle identifier itself is chapter 6.

Android: the upload key

1. Create a keystore once, and keep it forever — losing it means you can never update the app under the same listing:

   keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 \
     -validity 10000 -alias upload

2. Create android/key.properties (it is already in .gitignore; keep it out of source control):

   storePassword=<the password you just typed>
   keyPassword=<the same, unless you chose another>
   keyAlias=upload
   storeFile=<absolute path>/upload-keystore.jks

3. In android/app/build.gradle.kts, above android {, load the file:

   import java.util.Properties
   import java.io.FileInputStream
   
   val keystoreProperties = Properties()
   val keystorePropertiesFile = rootProject.file("key.properties")
   if (keystorePropertiesFile.exists()) {
       keystoreProperties.load(FileInputStream(keystorePropertiesFile))
   }

   then replace the buildTypes block at lines 37–43 with:

   signingConfigs {
       create("release") {
           keyAlias = keystoreProperties["keyAlias"] as String
           keyPassword = keystoreProperties["keyPassword"] as String
           storeFile = keystoreProperties["storeFile"]?.let { file(it) }
           storePassword = keystoreProperties["storePassword"] as String
       }
   }
   buildTypes {
       release {
           signingConfig = signingConfigs.getByName("release")
       }
   }

4. Check applicationId on line 28 is the identifier you settled on in chapter 6; it cannot change after the first upload.
5. Build the bundle Play wants:

   flutter build appbundle --release

   The file is build/app/outputs/bundle/release/app-release.aab. (flutter build apk --release gives an installable .apk under build/app/outputs/flutter-apk/ for sideloading onto a test phone; Play itself only takes the .aab.)

Play Console. Create the app, accept Play App Signing (Google keeps the final signing key; yours is the upload key), then Testing → Internal testing → Create release and drop the .aab in. Before production you will be asked for a privacy policy URL, the Data safety form, content rating, and store listing assets: a 512×512 icon, a 1024×500 feature graphic and phone screenshots. The screenshots/ folder that came with this download has 1920×1080 material to crop from. targetSdk is pinned to 36 in the Gradle file, which meets Play's current requirement.

If the app will talk to your back end, keep the INTERNET permission that is declared in android/app/src/main/AndroidManifest.xml; the debug build adds it silently, a release build does not, and without it every request fails with a socket error.

iOS: signing in Xcode, click by click

You need a Mac, Xcode, and a paid Apple Developer Program membership (the free tier can run on your own device but cannot upload to the store).

1. From the shearora_ui_kit folder run open ios/Runner.xcworkspace. Open the workspace, not Runner.xcodeproj; the project alone does not see the CocoaPods dependencies.
2. In the left-hand Project navigator click the blue Runner icon at the very top of the tree.
3. In the editor that opens, under TARGETS (not PROJECT) select Runner. There is a second target, RunnerTests; leave it.
4. Click the Signing & Capabilities tab along the top of that editor (the tabs read General · Signing & Capabilities · Resource Tags · Info · Build Settings …).
5. Tick Automatically manage signing and choose your Team from the drop-down. Xcode creates the signing certificate and the provisioning profile for you; if the Team list is empty, add your Apple ID under Xcode → Settings → Accounts first.
6. In the same panel check Bundle Identifier. It shows com.shearora.shearoraUiKit as shipped; type the one you chose in chapter 6. It must be registered to your team and unique across the App Store.
7. A red message under the Team field means the identifier is taken or the profile could not be made; the message says which. Fix it here before building — flutter build ipa only repeats Xcode's error.

Then build the archive:

flutter build ipa --release

The result is build/ios/ipa/<app name>.ipa, and the archive Xcode made along the way is build/ios/archive/Runner.xcarchive. Upload either: drag the .ipa into the free Transporter app from the Mac App Store, or double-click the .xcarchive to open it in Xcode's Organizer and click Distribute App → App Store Connect.

Info.plist: what App Review looks for

Apple rejects a build that uses a protected resource without a NS…UsageDescription string explaining why. This app uses none of them — no camera, no photo library, no location, no contacts, no microphone — so ios/Runner/Info.plist ships with no usage-description keys and needs none. Add the matching key the day you add a feature that does (for example NSCameraUsageDescription when you let customers photograph their cut). Two things in the plist you may want to touch: CFBundleDisplayName (Shearora, the name under the icon — chapter 6) and UISupportedInterfaceOrientations, which allows landscape on iPhone; remove the two landscape entries if you want the app locked to portrait like most booking apps. If you added an NSAppTransportSecurity exception while testing against a plain HTTP server (chapter 12), take it out before this build.

App Store Connect

Create the app record with the same bundle identifier, then fill in what Review asks of every app: screenshots for a 6.7″ and a 6.5″ iPhone (the 1290×2796 and 1284×2778 sizes; the simulator screenshots in screenshots/ are 1179×2556 and re-export at those sizes), a privacy policy URL, and the App Privacy questionnaire. Answer that questionnaire from what the build does: on sample data it collects nothing; connected to your back end it collects an email address and a name for account purposes, and bookings linked to that account. If sign-up is open on your server, Review will create an account to test with; give them the demo credentials from chapter 12 in the review notes so they do not have to.

Versioning both builds

Both stores read version: in pubspec.yaml (1.0.0+1 as shipped). The part before + is what users see; the part after is the build number, and each upload to either store needs one higher than the last. Change it there, not in Xcode or Gradle, so the two platforms stay in step.

23API reference

Everything the back end exposes to the app, in one place. Routes are declared in backend/routes/api.php (the four account routes) and backend/routes/companion.php (the seven record types, as apiResource groups). php artisan route:list prints the same list from the code, so if this table and the code ever disagree, the code wins.

Conventions that apply to every route

• Base path is /api/ under the server root; the app appends it itself (chapter 13), so the address you configure ends at the host.
• Requests and responses are JSON. Send Accept: application/json and Content-Type: application/json; a middleware forces the Accept header anyway so validation errors come back as JSON rather than a redirect.
• “Bearer” in the table means the route sits behind auth:sanctum: send Authorization: Bearer <token> with the token that login or register returned. Without it the answer is 401 {"message":"Unauthenticated."}.
• Single records come wrapped as {"data": {…}}; lists as {"data": […], "links": {…}, "meta": {…}} with Laravel's standard pagination fields (current_page, last_page, per_page, total).
• Validation failures are 422 with {"message": "…", "errors": {"field": ["reason"]}}.
• Bookings, cut cards, queue tickets and reviews are owned: a user sees and edits only rows with their own user_id; an admin token sees all of them. A row that is not yours answers 404.

Every endpoint

The three you will try first

These use the demo account the seeder creates, so they work against a fresh install with no setup beyond chapter 12. Replace the host as needed.

1. Sign in

curl -s -X POST http://127.0.0.1:8000/api/auth/login \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"email":"demo@shearora.app","password":"demo1234"}'

{
  "token": "3|k9Qm2vX8pR5tL1wN7yB4cD6fG0hJ2sA5eU8iO3zT",
  "user": { "id": 2, "name": "Demo User", "email": "demo@shearora.app", "role": "user" }
}

Keep the token value; the next two calls send it. A wrong password answers 422 with {"message":"Invalid credentials.","errors":{"email":["Invalid credentials."]}}.

2. List the caller's bookings

curl -s http://127.0.0.1:8000/api/bookings \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 3|k9Qm2vX8pR5tL1wN7yB4cD6fG0hJ2sA5eU8iO3zT"

{
  "data": [
    {
      "id": 12, "stylist_id": 4, "service_id": 10,
      "starts_at": "2026-09-15T09:00:00+00:00", "duration_min": 15,
      "status": "booked", "cut_card_id": null, "note": "", "price": 12.0,
      "created_at": "2026-09-14T10:20:00+00:00", "updated_at": "2026-09-14T10:20:00+00:00"
    }
  ],
  "links": { "first": "…/api/bookings?page=1", "last": "…/api/bookings?page=1", "prev": null, "next": null },
  "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 12 }
}

3. Create a booking

curl -s -X POST http://127.0.0.1:8000/api/bookings \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer 3|k9Qm2vX8pR5tL1wN7yB4cD6fG0hJ2sA5eU8iO3zT" \
  -d '{"stylist_id":4,"service_id":10,"starts_at":"2026-09-16T11:30:00+00:00",
       "duration_min":30,"status":"booked","price":28.0,"note":"Same as last time"}'

{
  "data": {
    "id": 13, "stylist_id": 4, "service_id": 10,
    "starts_at": "2026-09-16T11:30:00+00:00", "duration_min": 30,
    "status": "booked", "cut_card_id": null, "note": "Same as last time", "price": 28.0,
    "created_at": "…", "updated_at": "…"
  }
}

Leave out service_id and the same call answers 422 naming the field. Note that user_id is not in the body and is ignored if you send it: the owner is whoever the token belongs to.

24Environment variables

backend/.env is the one file the back end reads its configuration from, and backend/.env.example is the template install.sh copies it from. Every key in that template is listed here with its type, the value it ships with and what it controls, so you can check a shared-hosting install line by line instead of guessing. Values live in the config/*.php files, which read them with env(); nothing in app/ reads the environment directly.

If you only do one thing in this file, do the first group and set APP_DEBUG=false.

Two more files carry environment values for specific routes: backend/.env.docker is the copy Docker Compose uses (DB_CONNECTION=mysql, DB_HOST=db, DB_DATABASE=shearora, DB_USERNAME=root, DB_PASSWORD=root, APP_URL=http://localhost:8000) and backend/docker-compose.yml creates that MySQL database with the same name and root password. Neither is read on a real server.

After changing .env on a server where you have run php artisan config:cache, run it again: cached configuration does not notice edits to the file.

25Upgrading to a newer release

A newer release of this item arrives as a fresh zip with the same three folders. Nothing in it knows about your install, so the upgrade is a copy-over with a short list of files you keep. This chapter is that list, plus the order that keeps your data.

Before anything else

1. Back up the database. On shared hosting that is phpMyAdmin → Export; with Docker it is docker compose exec db mysqldump -uroot -proot shearora > backup.sql; with sqlite it is copying backend/database/database.sqlite.
2. Copy backend/.env and backend/public/uploads/ somewhere safe. Those two are yours and are not in any zip.
3. If you have not already, put both projects under version control (git init, commit) before editing anything. Then a future upgrade is git diff rather than memory.

Which files are yours and which are the release's

Doing the back end

1. Unzip the release next to your install, not over it.
2. Copy the “replace” folders from the new backend/ over yours. Do not copy .env.example over .env.
3. Run composer install --no-dev --optimize-autoloader (or ./install.sh, which does this and the next step for you).
4. Run php artisan migrate --force. This is safe on a live database. Every migration in this item only creates tables that do not exist yet (Schema::create); none drops or renames a column, and that rule holds for future releases too. Existing rows are untouched. Do not run migrate:fresh on a server — it drops every table first, including your bookings; it exists for the Docker demo only.
5. Do not run db:seed again. The seeder refuses to run twice anyway (it stops when the demo admin already exists), but there is nothing in it you want on a live install.
6. php artisan config:cache && php artisan route:cache && php artisan view:cache, then open /admin and sign in. If a page is blank, clear the caches once with php artisan optimize:clear and cache again.

Doing the app

1. Copy the “replace” files over your shearora_ui_kit/. With git, git status now shows exactly what changed; without it, keep the old folder until the new one builds.
2. Re-apply your own edits from the “keep” column where a replaced file needed them (typically only pubspec.yaml if you added packages, and app_binding.dart).
3. Raise version: in pubspec.yaml (both the name and the build number after the +; stores refuse a build number they have already seen), then flutter pub get, flutter analyze, flutter test, and build as in chapter 22.

26What is left for you to wire up

Chapter 20 says what is not in the box. This chapter is the other half of that promise: for each thing that is deliberately left open, where the seam is, what is already there, and what you bring. None of these is a hidden dependency — the app runs, ships and passes its tests exactly as it is — but if you are going to add one, start here rather than in a search box.

Push notifications

What is there. Two screens are built and wired end to end, and both stop one step short of a network:

• The settings switches. lib/app/modules/settings/settings_controller.dart holds four RxBools — bookingReminders, queueCalls, regrowthNudges, cancellationAlerts — and the screen reads and writes them. They are not persisted and nothing listens to them. The footnote on the screen says so.
• The notice feed. lib/app/modules/notifications/notifications_controller.dart builds its list from List<Notice> _seed() (lines 52–117), seven hard-coded notices of the four kinds the app can honestly send: a queue moving, a booking coming up, a cut growing out, the shop changing hours. Notice is a plain record of id · kind · title · body · at.

What is not there, on purpose. No push package in pubspec.yaml, no POST_NOTIFICATIONS permission in the Android manifest, no UIBackgroundModes in Info.plist, and no device-token table or route on the back end. Picking a push provider means picking a Firebase project or an APNs key on your behalf, which is a decision with a bill attached.

To wire one up (Firebase Cloud Messaging is the usual choice because it covers both platforms):

1. Add firebase_core and firebase_messaging to pubspec.yaml and run flutterfire configure; it writes lib/firebase_options.dart and the two platform config files.
2. Ask for permission and take the token where the app already knows who is signed in: after a successful login() in ApiRepository (line 113 onward), call FirebaseMessaging.instance.requestPermission() then getToken().
3. Send that token to the server. There is no route for it yet: add a device_tokens migration (user_id, token, platform), a POST api/device-tokens route in routes/companion.php behind auth:sanctum, and a one-method controller. Chapter 23 shows the shape every other route follows.
4. Replace _seed() with a stream: subscribe to FirebaseMessaging.onMessage and map each payload onto a Notice. The screen needs no change; it renders whatever the controller's list holds.
5. Make the four switches mean something: persist them (below) and send their state alongside the token so the server knows which kinds to send. On Android 13 and newer add <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/> to the manifest; on iOS turn on Push Notifications and Background Modes → Remote notifications under Signing & Capabilities (chapter 22 shows where that tab is).

Persisting the settings switches

Same file as above. Every switch is a RxBool with an initial value; swap each for a read at construction and a write in the setter against whichever key-value package you already use (shared_preferences, get_storage, hive all fit). It is a one-file change and the screen does not know it happened.

The sign-up code

lib/app/modules/auth/auth_controller.dart accepts any six digits on the verification screen (the text under the field says so, line 83). To make it real, send the phone number to your SMS provider when signUp() runs and check the code in verify() against what the provider issued; the 29-second resend timer and the six-box field are already there. The back end's register route does not take a phone number today — add the column in a migration and the rule in RegisterRequest when you do.

Keeping the sign-in token

ApiRepository.token is held in memory, so the app asks you to sign in again after a restart (chapter 13 explains why the choice was left to you). To remember it, read it from flutter_secure_storage when AppBinding builds the repository and write it after login(); the getter and the two call sites are the whole surface.

Live queue position

The walk-in queue advances on a 90-second timer in QueueController so the screen has something to show offline. With a server, the position should arrive from it: poll GET api/queue-tickets/{id}, or push it over the channel you set up above. The engine that turns a position into a wait and a leave-by time (queue_engine.dart) does not care where the number came from.

Where the numbers live

Business constants you are likely to want to change, so you do not have to search 71 Dart files for them. Line numbers are as shipped.

27Adding or removing a bottom tab

The bar at the bottom of the main screen is the app's own widget, _NavBar, in lib/app/modules/main/main_shell.dart — not Flutter's NavigationBar — so there is no theme to fight and everything about it is in that one file plus one line elsewhere. Four places change together; miss one and you get an index out of range on the tab you added.

1. The tab list, lines 38–43:

   static const List<_Tab> _tabs = [
     _Tab('Today',   Icons.schedule_outlined,        Icons.schedule),
     _Tab('Book',    Icons.event_available_outlined, Icons.event_available),
     _Tab('Walk-in', Icons.groups_outlined,          Icons.groups),
     _Tab('You',     Icons.person_outline,           Icons.person),
   ];

   Add or remove a _Tab(label, outlinedIcon, filledIcon) here. Keep labels to one short word: the bar gives each tab a quarter of the width and does not scroll.
2. The page list, lines 60–65, in the same order:

   const [TodayView(), BookView(), QueueView(), AccountView()][i]

   The two lists must be the same length; the shell indexes both with the same i. Pages sit in an IndexedStack so each keeps its scroll position, wrapped in TickerMode so only the visible one animates.
3. The jump helpers, lines 20–21 in MainController: goToBook() => index.value = 1 and goToQueue() => index.value = 2. Other screens call these to switch tabs, so if the order changes, change these numbers.
4. The binding. If the new page has a controller, register its Bindings in the bindings: list of the Routes.main entry in lib/app/routes/app_pages.dart (line 77), next to BookBinding() and QueueBinding(). The main shell is one route, so its tabs share that list.

Removing a tab is the same four edits in reverse; also delete any goTo… helper that pointed at it and search lib/ for its label so no button still tries to jump there. The walk-through in integration_test/ taps each tab by label and takes the screenshots in chapter 3, so add or remove its step too, and the widget test that counts tabs in test/ will tell you which number to update when it fails.