A prototype for Subsidiemaatje, an AI-powered assistant that helps citizens of Amsterdam find and understand subsidies that might match their plans.
Based on Amsterdam Design System Prototypes.
| Path | What it is |
|---|---|
frontend/ |
The app. Next.js 16 (App Router), including the API routes and all LLM logic in src/server. |
tests/ |
Black-box HTTP tests against the API. See tests/README.md. |
archive/ |
The original Flask backend, no longer used. See archive/README.md. |
DEPLOY_ENV_VARS.md |
Environment variables and Azure deployment. |
There is no separate backend process: the API routes in frontend/src/app/api
call the services in frontend/src/server in-process.
- Node.js 24 (see
frontend/.nvmrc) - An Azure account with access to the Foundry resource, and the Azure CLI
cd frontend
npm installBoth the LLM calls and the audio transcription run on Azure and authenticate with Entra ID, so sign in first:
az loginYour account needs the Cognitive Services OpenAI User role on the Foundry
resource — locally that means membership of EM4W-RND-o-ailab-members. Then
copy the example env file and fill it in:
cp .env.example .env.localMinimum configuration for local development:
# frontend/.env.local
AZURE_OPENAI_ENDPOINT=https://your-service.cognitiveservices.azure.com/
AZURE_OPENAI_API_VERSION=2025-01-01-preview
OPENAI_MODEL=your_azure_deployment_name
AZURE_TRANSCRIPTION_ENDPOINT=https://your-service.cognitiveservices.azure.com/speechtotext/transcriptions:transcribe?api-version=2024-11-15No API keys are needed. AZURE_OPENAI_API_KEY and AZURE_TRANSCRIPTION_KEY
exist only as break-glass fallbacks and should stay unset — the Foundry resource
has disableLocalAuth: true, so a key that is set will fail with
403 AuthenticationTypeDisabled. See DEPLOY_ENV_VARS.md
for the full list and for deploying to App Service.
.env.example is the committed template and holds no secrets; .env.local is
your own copy and is never committed.
npm run devThe prototype is then available at http://localhost:3000, or another port if 3000 is taken.
Build and run a production bundle with npm run build and npm start.
To speed up development and avoid API costs, several pages can serve canned
responses instead of calling Azure. Set NEXT_PUBLIC_USE_DUMMY_DATA=true in
.env.local to enable it, false to turn it off.
| Page | Fixture |
|---|---|
subsidie-bestuderen |
src/data/dummy-subsidy-explanation.ts |
subsidie-suggesties |
src/data/dummy-shortlist.ts |
With dummy data enabled, the vertel-uw-plan page shows an extra
"Test search buurtfeest Noord" link for quick testing.
To regenerate the fixtures from live responses, start the dev server and run:
npm run refresh-dummy-dataIt checks that the server is up, calls the endpoints with test data, rewrites the fixture files, and reports progress and errors along the way.
The endpoint tests are pytest-based and run over HTTP against a running server. See tests/README.md.
The prototype uses the Amsterdam Design System React library for its UI components. Component documentation and examples live in the Storybook.