Development Runbook

Symfony app

The main app lives in app/.

cd app
composer install
yarn install
yarn dev
php bin/console cache:clear
php bin/console debug:router

Useful Symfony inspection commands:

php bin/console debug:router --format=json
php bin/console debug:container
php bin/console doctrine:migrations:status
php bin/console doctrine:schema:validate

Fumadocs site

The documentation site lives in docs-site/.

cd docs-site
bun install
bun run dev
bun run build
bun run typecheck

Docs content lives under docs-site/content/docs. Fumadocs serves it under /docs.

Calculation commands

cd app
php bin/console app:allowances:recalculate-timesheets --force
php bin/console app:award:recalculate-timesheets --force
php bin/console app:timesheets:recalculate-hours
php bin/console app:timesheets:recalculate-risk

Use targeted ids or limits when available before running broad recalculation in shared environments.

Xero and Auth0 diagnostics

cd app
php bin/console app:xero:test-connection
php bin/console app:xero:debug
php bin/console app:auth0:inspect-token
php bin/console app:sync-users-to-auth0

Shell helpers also exist under scripts/ for Auth0 tokens, local /me testing, project assignment tests, and mobile login checks.

Documentation verification checklist

Before treating the docs as complete:

1. Run Fumadocs MDX generation or build.
2. Validate every meta.json file parses.
3. Validate every MDX file has frontmatter.
4. Run a grep for unwanted dash characters if maintaining the no em-dash writing style.
5. Re-run route inventory if controllers changed.
6. Update docs pages when calculation or workflow services change.

Docker Compose docs service

The root docker-compose.yml includes a docs-site service. Start only the documentation site with:

docker compose up docs-site

Open http://localhost:3001/docs. The host port can be overridden with DOCS_PORT, for example:

DOCS_PORT=3010 docker compose up docs-site

The service runs bun install --frozen-lockfile and then starts Fumadocs on container port 3000. Named volumes keep node_modules, .next, and .source out of the repository checkout.