biibaye/fleetbase-source/AGENTS.md

AGENTS.md — Fleetbase

Architecture

• Dual-stack monorepo: Laravel 10 (PHP) backend + Ember.js 5.4 frontend + 12 Git submodules
• Docker services: application (FrankenPHP/Caddy :8000), httpd (:80→8000), console (Nginx :4200), socket (SocketCluster :38000), database (MySQL 8.0 :3306), cache (Redis), queue, scheduler
• Console port 4200, API port 8000 — both must be free or mapped differently
• Packages: Each packages/<name>/ is a Git submodule; contains PHP (composer.json + server/) and/or Ember code (addon/, app/, extension.json)
• Core packages: core-api, ember-core, ember-ui, dev-engine — framework layers all extensions depend on

Prerequisites & Constraints

• PHP >= 8.0, <= 8.2.30 (strict upper bound — 8.3+ will break)
• Node.js >= 22
• pnpm is the JS package manager (not npm/yarn) — pnpm@11.0.9
• Composer uses private registry at https://registry.fleetbase.io — authentication may be required for private packages
• Git submodules must be initialized: git submodule update --init --recursive

Commands

Docker (most common)

docker compose up -d                          # Start all services
docker compose exec application bash          # Shell into API container
docker compose exec application php artisan … # Run artisan commands
docker compose exec application bash -c "./deploy.sh"  # Run deployment script

Backend (api/)

cd api && composer install    # Install PHP deps (uses fleetbase registry)
cd api && php artisan …       # Laravel artisan (run inside container or locally with DB access)
cd api && php artisan test    # Run PHPUnit tests
cd api && ./vendor/bin/php-cs-fixer fix   # Fix PHP style
cd api && vendor/bin/phpstan analyse       # Static analysis (in packages with phpstan.neon.dist)

Frontend (console/)

cd console && pnpm install    # Install JS deps
cd console && pnpm start      # Ember dev server (requires API + socket running)
cd console && pnpm lint       # ESLint + stylelint + template-lint
cd console && pnpm test       # Lint + ember test (QUnit via Testem)
cd console && pnpm build      # Production build → dist/

Single test runs

cd api && php artisan test --filter=MyTest           # PHP: single test class
cd api && php artisan test --filter=MyTest::testFoo  # PHP: single test method
cd console && pnpm test --filter='My test name'       # Ember: filter by test name
cd console && pnpm test --server                      # Ember: watch mode

Extensions (Custom Packages)

Each extension is a Git submodule under packages/<name>/ with this structure:

extension.json          # Metadata (name, version, engine, api)
composer.json           # PHP dependencies (if has API)
package.json            # JS dependencies (if has Ember engine)
server/                 # PHP API code (PSR-4)
addon/                  # Ember engine files
app/                    # Ember app files

Scaffold a new extension

flb scaffold                            # CLI wizard
# Or manually: create packages/<name>/ with extension.json, composer.json, package.json
# Register it as submodule: git submodule add <repo-url> packages/<name>

Link local extensions for development

node scripts/package-linker.mjs                 # Symlink all packages/ into api/ and console/

Package registry flow

flb register                              # One-time: create registry account
flb verify -e <email> -c <code>           # Verify email
flb generate-token -e <email>             # Get auth token
flb set-auth <token>                      # Save token for installs
flb install fleetbase/<extension>         # Install extension from registry

Production Deployment (VPS: 37.27.183.102)

SSH key: Config/fleet_key  (chmod 600, OpenSSH RSA private key)
SSH command: ssh -i Config/fleet_key root@37.27.183.102

Key env vars for production (docker-compose.override.yml)

• ENVIRONMENT=production, APP_DEBUG=false
• APP_KEY — generate with docker compose exec application bash -c "php artisan key:generate --show"
• APP_URL, CONSOLE_HOST — set to actual domain/IP
• SESSION_DOMAIN — domain for session cookies
• SOCKETCLUSTER_OPTIONS — restrict origins to production domains
• MAIL_* — configure real mailer (not log driver)
• FILESYSTEM_DRIVER=s3 — S3 for file storage (not local disk)
• GOOGLE_MAPS_API_KEY, IPINFO_API_KEY, TWILIO_* — for full feature set
• REGISTRY_HOST, REGISTRY_PREINSTALLED_EXTENSIONS — extension registry config
• OSRM_HOST — routing engine URL

Production checklist

1. Copy repo to server, run docker compose up -d (with correct override)
2. Ensure ports 80/443/8000/4200/38000 are open in firewall
3. Set up SSL/reverse proxy (Caddyfile for API, Nginx for console)
4. Use external/managed MySQL in production (not bundled container)
5. S3 for file storage (not local disk)
6. Restrict SOCKETCLUSTER_OPTIONS origins

Environment File Locations

Env	Notes
docker-compose.override.yml	Primary — env vars injected into all Docker services
api/.env	Only needed for local PHP runs outside Docker
api/.env.example	Template reference
console/environments/.env.development	Ember dev env
console/environments/.env.production	Ember prod env

Git Submodule Gotchas

• Always git submodule update --init --recursive after clone
• Submodules track specific commits — working on a package means committing inside packages/<name>/ first, then updating the parent repo's submodule pointer
• After git pull in parent, run git submodule update --recursive to sync submodules
• Package linker script (scripts/package-linker.mjs) symlinks submodules into api/console/ for local dev — run it after changing module structure

Linting (all layers)

Layer	Tool	Command
PHP	php-cs-fixer	./vendor/bin/php-cs-fixer fix (in api/ or package)
PHP	PHPStan	vendor/bin/phpstan analyse (in packages with neon config)
JS	ESLint + Prettier	pnpm lint (in console/)
CSS	Stylelint	pnpm lint:css
Templates	ember-template-lint	pnpm lint:hbs
i18n	fleetbase-intl-lint	pnpm lint:intl

Conventions

• Ember Octane edition — use Glimmer components (@glimmer/component), <template> tags, @tracked
• Tailwind CSS 3.4 is the styling framework, inter-ui is the typeface
• PHP controllers return API resources via \App\Http\Resources\ namespace
• Caddy replaces traditional Nginx/Apache for the API server (FrankenPHP)
• SocketCluster handles real-time WebSocket connections
• Prettier config: 4-space tabs, single quotes for JS, double quotes for HBS, 190 print width

---

Session: 2026-05-24 — Biibaye Branding Extension

Branch Strategy

• main: Clean upstream from github.com:fleetbase/fleetbase. Never commit here — only git pull.
• custom-production: Working branch with custom branding + WhatsApp alterations. Created off main at v0.7.41.

Private Git Repo

• URL: ssh://git@git.1.warancloud.com:2222/Ali/biibaye.git
• SSH Key: ~/.ssh/deploy_key (same key present on both local and VPS)
• SSH Config entry (on VPS at /root/.ssh/config):

  Host git.1.warancloud.com
      IdentityFile ~/.ssh/deploy_key
      IdentitiesOnly yes
      AddKeysToAgent yes
      port 2222
      user git
  

New Extension: packages/biibaye-branding/

Git submodule pointing at private repo. Provides all custom branding:

packages/biibaye-branding/
├── extension.json              # "Biibaye Branding" v1.0.0
├── package.json                # @biibaye/branding, fleetbase-extension + ember-engine keywords
├── index.js                    # Ember addon entry
├── config/environment.js       # Engine config
├── addon/
│   ├── engine.js               # Minimal Ember Engine (required by Fleetbase build system)
│   └── extension.js            # Branding logic — runs at Ember boot
└── public/
    ├── favicon/                # 22 Biibaye-branded icon files (apple-icon-*, android-icon-*, ms-icon-*)
    └── images/                 # logo SVGs, icon PNGs

extension.js does 5 things on boot:

1. document.title = "Biibaye - Delivery System" (in both setupExtension and onEngineLoaded)
2. intl.addTranslations('en-us', { 'app.name': 'Biibaye' }) — runtime translation injection
3. Injects CSS: --primary: #FF4500, dark theme background-color: #343538
4. Replaces all <link rel="icon"> / <link rel="apple-touch-icon"> with Biibaye files
5. Updates meta tags: msapplication-TileColor, theme-color, msapplication-TileImage

Why translations/en-us.yaml was removed: ember-intl merges translations at build time with host app files taking HIGHEST priority. console/translations/en-us.yaml defines app.name: Fleetbase, which always wins over any addon's app.name. Other Fleetbase extensions avoid this by using namespaced keys (e.g., fleet-ops.*, storefront.*). Solution: in overrideAppName(), look up the intl service from appInstance and call intl.addTranslations('en-us', { 'app.name': 'Biibaye' }) at runtime.

Key implementation detail: setupExtension() calls universe.extensionManager.ensureEngineLoaded('@biibaye/branding') to force the engine to boot. Without this, the engine never loads (root-mounted engines have no route to trigger boot). onEngineLoaded re-sets translation and title after boot, defeating any race with ember-page-title re-render.

Deploy Script: /opt/fleetbase/scripts/deploy-biibaye.sh

Located on VPS. Handles the Docker build context issue (console build context is ./console/, not repo root). Steps:

1. git pull origin main in extension submodule
2. Copies extension into console/packages/biibaye-branding/ (Docker build context)
3. Copies public/favicon/* and public/images/* into console/public/ (so files serve from root /favicon/* URLs)
4. NEW — Patch console/app/index.html: Replace Fleetbase defaults to prevent branding flash during reload:

   sed -i 's|<title>Fleetbase Console</title>|<title>Biibaye - Delivery System</title>|' console/app/index.html
   sed -i 's|content="#da532c"|content="#FF4500"|' console/app/index.html
   sed -i 's|content="#ffffff"|content="#FF4500"|' console/app/index.html
   sed -i 's|href="/favicon/apple-touch-icon.png"|href="/favicon/apple-icon-180x180.png"|' console/app/index.html
   sed -i 's|href="/favicon/android-chrome-192x192.png"|href="/favicon/android-icon-192x192.png"|' console/app/index.html
   sed -i 's|href="/favicon/android-chrome-256x256.png"|href="/favicon/android-icon-144x144.png"|' console/app/index.html
   sed -i 's|color="#5bbad5"|color="#FF4500"|' console/app/index.html
   

5. NEW — Patch console/tailwind.config.js: Replace sky-500 blue (#3485e2) palette with Biibaye orange (#FF4500). This is the PRIMARY fix for the color theme — without this, Fleetbase shows blue buttons/accents because all UI uses Tailwind sky-* classes directly:

   sed -i "s/'#e6f0fb'/'#FFF0E6'/" console/tailwind.config.js
   sed -i "s/'#bad5f5'/'#FFD0B3'/" console/tailwind.config.js
   sed -i "s/'#8dbbef'/'#FFB380'/" console/tailwind.config.js
   sed -i "s/'#61a0e8'/'#FF7A33'/" console/tailwind.config.js
   sed -i "s/'#3485e2'/'#FF4500'/" console/tailwind.config.js
   sed -i "s/'#1c6cc7'/'#E03D00'/" console/tailwind.config.js
   sed -i "s/'#16539a'/'#B33100'/" console/tailwind.config.js
   sed -i "s/'#103b6d'/'#8A2600'/" console/tailwind.config.js
   sed -i "s/'#092341'/'#611A00'/" console/tailwind.config.js
   

6. Adjusts pnpm workspace paths for Docker (../packages/ → packages/)
7. Injects COPY packages/ packages/ before pnpm install in Dockerfile (so pnpm resolve the link dependency)
8. Removes --frozen-lockfile during build (new dep not in lockfile)
9. Runs docker compose build console --no-cache
10. Restores all original configs (Dockerfile, package.json, workspace, index.html, tailwind.config.js) — restore is critical to keep the clean checkout intact
11. Restarts console, httpd, application containers

Why both tailwind.config.js patching AND extension.js CSS injection?

• tailwind.config.js patching (build-time): Changes primary color at the Tailwind compilation level. This prevents the blue flash because the compiled @fleetbase/console.css already contains orange colors. However, ember-ui's pre-compiled CSS in vendor.css (like .btn.btn-primary) uses #3485e2 at @apply compile time and is NOT affected by the console's tailwind config.
• extension.js CSS injection (runtime): Acts as a safety net, overriding any blue that leaks through from vendor.css with !important rules. Covers the gap where ember-ui's pre-compiled CSS still references blue.

To update branding assets in the future:

# Locally: replace files in packages/biibaye-branding/public/ then:
cd packages/biibaye-branding
git add -A && git commit -m "Update assets" && git push origin main

# On VPS:
ssh root@37.27.183.102
/opt/fleetbase/scripts/deploy-biibaye.sh

VPS Changes Made (37.27.183.102)

What	Where	Details
custom-production branch	/opt/fleetbase/	Created off main, committed submodule addition
packages/biibaye-branding submodule	/opt/fleetbase/.gitmodules	Points at private repo
APP_NAME: "Biibaye"	docker-compose.override.yml	Was "Fleetbase"
MAIL_FROM_NAME: "Biibaye"	docker-compose.override.yml	Was "Fleetbase"
EXTENSIONS: "@biibaye/branding"	console/fleetbase.config.json	Critical — without this extension.js never runs
SSH config	/root/.ssh/config	Added git.1.warancloud.com entry
SSH key	/root/.ssh/deploy_key	Copied for private repo access
Deploy script	/opt/fleetbase/scripts/deploy-biibaye.sh	Rebuilds console with branding

VPS State (Pre-existing)

What	Value
Fleetbase version	v0.7.41
Domains	api.biibaye.com, console.biibaye.com, socket.biibaye.com
.env.development	API: http://37.27.183.102:8000
.env.production	API: https://api.biibaye.com
fleetbase.config.json	API/Socket prod URLs
Docker services	All running (scheduler unhealthy — pre-existing)

Branding Spec

Property	Value
App name	Biibaye
Window title	Biibaye - Delivery System
Primary color	#FF4500
Dark theme background	#343538
Favicon files	22 Biibaye-branded icons (apple-icon-, android-icon-, ms-icon-*)
Logo files	SVG-02.svg, icon.svg, icon.png, fleetbase-logo-svg.svg

Troubleshooting: app.name Translation

Problem: {{t "app.name"}} still shows "Fleetbase" after extension loaded.

Root cause: ember-intl v6.3.2 build-time merge gives host app (console/translations/en-us.yaml) priority over addon translations. Key app.name: Fleetbase at line 2 of console translations defeats any addon override.

Fix: Instead of relying on build-time translations/en-us.yaml, use runtime injection via intl.addTranslations():

// In setupExtension + onEngineLoaded:
const intl = appInstance.lookup('service:intl');
intl.addTranslations('en-us', { 'app.name': 'Biibaye' });

Verification: Check that appInstance.lookup('service:intl') returns the intl service and addTranslations method exists. ember-intl 6.3.2 has this API confirmed via addTranslations in test-support.js.

Troubleshooting: Primary Color Not Applied (CSS Variables Don't Work)

Problem: Extension injected :root { --primary: #FF4500; } but Fleetbase UI still shows blue (#3485e2).

Root cause: Fleetbase does NOT use CSS custom properties for theming. All colors are hardcoded via Tailwind's sky-* palette (e.g., bg-sky-500, text-sky-500). The --primary variable is never referenced by any Fleetbase component or CSS rule.

Fix (two layers):

1. Build-time — Patch tailwind.config.js to replace the sky palette with Biibaye orange before the Docker build. This changes all sky-* class definitions in the compiled console.css.

2. Runtime — extension.js injects !important CSS overrides targeting Tailwind utility classes (.bg-sky-500, .text-sky-500, etc.) and component classes (.btn.btn-primary). This catches any blue that leaks through from ember-ui's pre-compiled vendor.css.

---

Session: 2026-05-25 — CSS Color Fix + Fleetbase UI Removal

Two critical fixes applied

1. Post-build CSS color patching (the approach that finally worked)

Problem: Building tailwind.config.js patches into Docker failed repeatedly (host-side sed, Dockerfile-internal Node.js patching, post-build sed — none worked). The built CSS always retained Fleetbase blue rgba(52, 133, 226, ...).

Solution: console/patch-css-colors.js — a Node.js script that runs AFTER pnpm build inside the Dockerfile. It walks the dist/ directory tree, finds all .css files, and replaces Fleetbase blue hex/RGB values with Biibaye orange directly in the compiled output.

RUN pnpm build --environment $ENVIRONMENT
RUN node patch-index-html.js && node patch-css-colors.js

Result: 4 CSS files patched (console.css, vendor.css, fleetops-engine/engine.css, registry-bridge-engine/engine.css). Zero blue references remain — 11 orange refs in console.css, 16 in vendor.css.

2. Extension loading fix

Problem: The @biibaye/branding extension never loaded because extensions.json (generated at build time by scanning node_modules) didn't include it. The deploy script's sed commands to modify pnpm workspace paths were no-ops because the source files never contained the biibaye entries to begin with.

Solution: Added "@biibaye/branding": "link:../packages/biibaye-branding" to console/package.json dependencies. Committed to custom-production branch. The deploy script converts the link path from link:../packages/ (host) to link:packages/ (Docker build context) via sed. This is the ONLY reliable sed in the deploy script — the workspace.yaml sed was removed.

Result: extensions.json now contains @biibaye/branding. The extension loads, all runtime features fire on boot.

Extension.js Enhancements

Added in this session:

1. CSS color overrides — replaced non-functional --primary: #FF4500 CSS variables with !important overrides for actual Tailwind classes (.bg-sky-500, .text-sky-500, .border-sky-500, .btn.btn-primary, etc.) and dark theme body[data-theme="dark"] background.

2. Fleetbase UI removal:

   • Menu links — CSS rules hide .support-user-nav-item (Help & Support), .docs-user-nav-item (Documentation), and a[href*="discord.gg"] (Discord).
   • Default widgets — removeFleetbaseWidgets() accesses the widget registry and removes dashboard#fleetbase-blog and dashboard#fleetbase-github-card from both widget and default-widget lists.

Patch Scripts (in console/ directory on VPS)

Script	Purpose	When runs
patch-index-html.js	Replace Fleetbase title/favicon/meta in dist/index.html	Docker: after pnpm build
patch-css-colors.js	Replace Fleetbase blue → Biibaye orange in all compiled CSS	Docker: after pnpm build
patch-index-html.py	Same as .js version but in Python (used on host)	Deprecated — uses .js version now
patch-tailwind.js	Replace sky palette in tailwind.config.js	Deprecated — didn't work reliably in Docker

Deploy Script (current version)

Located at /opt/fleetbase/scripts/deploy-biibaye.sh on VPS. Current steps:

1. git pull origin main in extension submodule
2. Copy extension into console/packages/biibaye-branding/
3. Copy public assets (favicon, images) into console/public/
4. Run python3 patch-index-html.py on host (patches source app/index.html)
5. Adjust Dockerfile: remove --frozen-lockfile, inject COPY packages/ packages/, inject RUN node patch-index-html.js before build
6. Adjust package.json: convert link:../packages/ → link:packages/ for Docker context
7. docker compose build console --no-cache
8. Restore all modified files (index.html, package.json, Dockerfile)
9. Restart containers

Fleetbase Source Changes (custom-production branch)

File	Change
console/package.json	Added "@biibaye/branding": "link:../packages/biibaye-branding" in dependencies
AGENTS.md	All session documentation

These changes are mirrored in the custom-pr branch of the biibaye extension repo under fleetbase-source/ for safekeeping.