MGA Sample Template

The MGA (Managing General Agent) sample scaffolds a complete insurance platform with multiple interconnected services — an API backend, a web frontend, and a report generation worker.

What Gets Created

tawa sample --mga my-mga

Directory	Framework	Description
`my-mga-api/`	Express	Backend — policies, quotes, claims
`my-mga-web/`	Next.js	Frontend — dashboard, policy list, quote wizard
`my-mga-reports/`	Worker	Report generation — bordereaux, loss runs

Each directory is a standalone deployable service with its own catalog-info.yaml, package.json, and health endpoint. They communicate via internal dependencies resolved by the builder at deploy time.

API Service

# my-mga-api/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-mga-api
  annotations:
    insureco.io/framework: express
spec:
  type: service
  lifecycle: production
  owner: my-org
  routes:
    - path: /api/policies
      methods: [GET, POST, PUT]
      auth: required
    - path: /api/quotes
      methods: [GET, POST]
      auth: required
    - path: /api/claims
      methods: [GET, POST]
      auth: required
  databases:
    - type: mongodb

OAuth is automatic — the builder provisions BIO_CLIENT_ID and BIO_CLIENT_SECRET on every deploy.

Web Service

# my-mga-web/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-mga-web
  annotations:
    insureco.io/framework: nextjs
spec:
  type: service
  lifecycle: production
  owner: my-org
  internalDependencies:
    - service: my-mga-api
      port: 3000

The builder resolves my-mga-api to a K8s DNS URL and injects it as MY_MGA_API_URL. Your frontend calls the API at process.env.MY_MGA_API_URL without hardcoding URLs.

Reports Worker

# my-mga-reports/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-mga-reports
  annotations:
    insureco.io/framework: worker
spec:
  type: service
  lifecycle: production
  owner: my-org
  internalDependencies:
    - service: my-mga-api
      port: 3000
  queues:
    - name: generate-report
      endpoint: /internal/jobs/generate-report
      concurrency: 2
      retries: 3
      timeoutMs: 120000

Deploying All Three Services

# Deploy API first (web and reports depend on it)
cd my-mga-api && tawa deploy --prod

# Deploy web and reports in any order
cd ../my-mga-web && tawa deploy --prod
cd ../my-mga-reports && tawa deploy --prod

Each service gets its own URL:

Service	URL
API	`my-mga-api.tawa.insureco.io`
Web	`my-mga-web.tawa.insureco.io`
Reports	`my-mga-reports.tawa.insureco.io`

Common Customizations

What to change	Where
Add more API routes	`my-mga-api/catalog-info.yaml` routes section
Change pod size	`insureco.io/pod-tier` annotation
Add a database to the web app	`spec.databases` in `my-mga-web/catalog-info.yaml`
Add email/SMS	Add `septor: relay` to `internalDependencies`
Set API gas pricing	`gas:` field on each route
Add scheduled report generation	`spec.schedules` in `my-mga-reports/catalog-info.yaml`

Key Facts

Each service must be deployed separately — there's no single tawa deploy for a multi-service template
Internal dependencies are resolved at build time — deploy the API before services that depend on it
All three services share the same spec.owner — they belong to one org's wallet
The reports worker uses framework: worker — no public HTTP routes, only internal queue endpoints

Last updated: February 28, 2026