MGA Sample Template

What gets created

Running tawa sample --mga my-mga generates three service directories, each with its own catalog-info.yaml, package.json, and health endpoint:

tawa sample --mga my-mga

# Output:
#   my-mga-api/
#   my-mga-web/
#   my-mga-reports/

Each directory is a standalone deployable service. They communicate via internal dependencies resolved by the builder at deploy time.

API service structure

The my-mga-api/ service is an Express API with TypeScript that provides the core insurance operations.

catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-mga-api
  description: MGA insurance 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

Web service structure

The my-mga-web/ service is a Next.js 14 application with App Router that provides the insurance platform UI.

catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-mga-web
  description: MGA insurance portal
  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 Kubernetes DNS URL and injects it as MY_MGA_API_URL in the web service's environment. Your frontend calls the API at process.env.MY_MGA_API_URL without hardcoding any URLs.

Reports worker structure

The my-mga-reports/ service is an Express worker that generates policy reports, bordereaux, and loss runs. It has no public routes and is not exposed via ingress.

catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-mga-reports
  description: MGA report generation worker
  annotations:
    insureco.io/framework: worker
spec:
  type: service
  lifecycle: production
  owner: my-org
  internalDependencies:
    - service: my-mga-api
      port: 3000
  databases:
    - type: mongodb

Multi-service setup

Each service declares its dependencies in catalog-info.yaml under spec.internalDependencies. During deploy, the builder resolves each dependency to a Kubernetes cluster DNS URL via Koko.

# In my-mga-web/catalog-info.yaml
spec:
  internalDependencies:
    - service: my-mga-api
      port: 3000

The builder resolves this to the full cluster DNS address:

http://my-mga-api.my-mga-api-prod.svc.cluster.local:3000

This URL is injected as an environment variable named MY_MGA_API_URL (derived from the service name, uppercased with hyphens replaced by underscores). Your app reads it from process.env like any other env var.

Dependency graph

my-mga-web ──────> my-mga-api ──────> MongoDB
                        ^
my-mga-reports ─────────┘ ──────────> MongoDB

Both the web frontend and the reports worker depend on the API service. The API service and the reports worker each have their own MongoDB database (auto-provisioned separately).

Deploying

Each service is deployed independently. Deploy the API service first because the web and reports services depend on it.

Deploy order

1. API — deploy first (other services depend on it)
2. Web — deploy after the API is running
3. Reports — deploy last (depends on API)

Commands

# 1. Deploy the API service
cd my-mga-api
tawa preflight
tawa deploy

# 2. Deploy the web frontend
cd ../my-mga-web
tawa preflight
tawa deploy

# 3. Deploy the reports worker
cd ../my-mga-reports
tawa preflight
tawa deploy

Production deploys

Follow the same order with the --prod flag:

cd my-mga-api && tawa deploy --prod
cd ../my-mga-web && tawa deploy --prod
cd ../my-mga-reports && tawa deploy --prod

After deploying, the services are available at:

Common customization

The MGA sample is a starting point. Here are common ways to extend it after scaffolding.

Add PlugINS integrations

The Tawa PlugINS store provides pre-built insurance integrations. Common additions for MGA platforms:

Add Redis for caching

If your quote flow involves expensive rate calculations, add Redis to the API service for caching:

# In my-mga-api/catalog-info.yaml
spec:
  databases:
    - type: mongodb
    - type: redis

This injects REDIS_URL into the API pod on the next deploy. Use it to cache quote results, rate tables, or session data.

Connect to OFAC Check

For compliance screening on policy applicants, add an internal dependency to an OFAC screening service:

# In my-mga-api/catalog-info.yaml
spec:
  internalDependencies:
    - service: ofac-check
      port: 3000

The builder resolves this to the cluster DNS URL and injects it as OFAC_CHECK_URL in your pod environment.

Related

• catalog-info.yaml Reference — full field reference for all configuration options
• Databases — how database provisioning works
• OAuth Integration — Bio-ID auto-provisioning details
• Platform Architecture — how platform services connect
• Getting Started — deploy your first service