Timatic API

The High Level Design documentation will give you a broader understanding of the application.

The Business Rules documentation will help you understand the business logic of BudgetVersions, Periods and BudgetUsage calculations.

Setup local development environment

cp .env.example .env
composer install
npm install
npm run build
php artisan key:generate
php artisan timatic:install
herd link api.app.timatic --secure

npm run build compiles the Filament admin theme and the stylesheet for the integration consent pages. Deployments must run it too, otherwise those pages render unstyled.

timatic:install runs migrations, creates the first admin user, and optionally generates an API token and seeds dummy data.

Authentication

A deployment runs exactly one identity provider. Set SOCIALITE_DRIVER to azure, google or auth0 and fill that provider's credentials in .env; auth/redirect answers 503 until it can, so a misconfigured deployment says so itself rather than failing inside the provider.

Browser callers authenticate with a bearer token, not the session. ApiClientSeeder registers who may ask for one, which redirect uris their codes may travel to and how long their tokens live. Re-run it after changing APP_FRONTEND_URL or EXTENSION_IDS:

Client	Redirect uris from	Lifetime
web	APP_FRONTEND_URL + /auth/callback	30 days
chrome-extension	EXTENSION_IDS	90 days

Integration packages register clients of their own. A registered http://127.0.0.1 or http://[::1] redirect uri matches any port (RFC 8252 §7.3), so a command line client can listen on whichever port is free. A client with sliding_expiration gets its token's expiry pushed forward on every use, so the token only lapses after its lifetime without use.

The web session remains in use by the Filament admin panel, the integration consent pages and the oauth/authorize consent screen. Keep SESSION_SAME_SITE=lax and SESSION_SECURE_COOKIE=true: lax is what lets the cookie travel on the browser's top level navigations to oauth/authorize and auth/logout.

Dummy data

To (re)seed dummy data at any time:

php artisan db:seed --class=DummySeeder

API documentation

/docs serves the committed public/api.json, which the export-api-docs workflow regenerates with Scramble Pro on pushes to main. Pro is not in composer.json, so locally /docs shows the free Scramble output, without filter, include and pagination parameters.

To regenerate public/api.json locally, set the license credentials once and run the export. It installs Pro temporarily and restores composer.json/composer.lock afterwards:

composer config -g http-basic.satis.dedoc.co <username> <password>
composer docs:api

Commands

Rebundle entry suggestions

Deletes all open (not accepted, not rejected) entry suggestions and rebundles their activities chronologically using the current matching rules:

php artisan timatic:rebundle-suggestions [--user=1] [--from=2026-06-01] [--to=2026-06-30]

Pause queue workers before running this against live data, so the CreateSuggestion listener cannot attach new activities while suggestions are being rebundled.

License

Copyright (c) 2025 Timatic.

You may use this software internally within your organization for any purpose. Selling, sublicensing, or providing the software to third parties for commercial gain is prohibited. See LICENSE.txt for full terms.