Quickstart
Make an authenticated request, discover contracts, and find the owning module.
1. Discover the API
With the backend running, open:
http://localhost:8080/swagger-ui.htmlThe generated OpenAPI document lives at:
http://localhost:8080/v3/api-docs2. Call a module
Every protected operation accepts a bearer token from the deployment's OIDC provider. The example uses a placeholder credential:
curl --request GET \
--url http://localhost:8080/referential/v1/carriers \
--header 'Authorization: Bearer <your-token>'Permissions are action-specific. Carrier reads require
referential.carrier:read; carrier mutations require
referential.carrier:write.
3. Follow ownership
When a request changes a fact, find the module that owns it:
| Fact | Owner |
|---|---|
| Carrier, vehicle, line, station, permit | referential |
| Effective business policy | rules |
| Display point or presentation profile | siv |
| Dated departure | scheduling |
| Vehicle/bay commitment | allocation |
| Observed station passage | cycle |
| Traveler ticket and counter money | ticketing |
| Vehicle-stay invoice | billing |
Call another module only through its published API. Never read or write its schema directly.
4. Regenerate the frontend contract
With the backend running:
pnpm --dir ../smartgare-frontend --filter @smartgare/api generateThe generated declaration is committed so every frontend build consumes the reviewed HTTP contract.
5. Explore the MCP mirror
Enable the backend mcp profile to serve the authenticated Streamable HTTP
endpoint at /mcp. Referential tools follow the
referential_<verb>_<noun> naming convention and invoke the same use cases as
REST.