# Scaffold Service

## What this skill covers
How to scaffold a new service on Tawa using `tawa sample` templates.

## Available Templates

| Template | Command | What You Get |
|----------|---------|-------------|
| Static Site | `tawa sample --static my-site` | HTML/CSS served by nginx, no build step |
| Express API | `tawa sample --api my-svc` | TypeScript Express API, Vitest, Dockerfile, Helm chart |
| Next.js App | `tawa sample --nextjs my-app` | Next.js 14 standalone, Bio-ID auth, Dockerfile, Helm |
| Full MGA | `tawa sample --mga my-mga` | API + web portal + reporting, Bio-ID SSO, multi-service |

## Step-by-Step

### 1. Create your account (if not done)
```bash
npm install -g tawa
tawa signup          # Opens Bio-ID registration
tawa whoami          # Verify: admin@example.com (org: my-org)
```

### 2. Scaffold
```bash
tawa sample --api my-new-service
cd my-new-service
```

### 3. Review generated files
Every template includes:
- `catalog-info.yaml` — pre-configured for the framework
- `package.json` — with build/start scripts
- Source code with health endpoint
- `.gitignore`

Templates may also include:
- `Dockerfile` — framework-specific (optional, builder can generate)
- `helm/` — Helm chart directory
- `.env.example` — environment variables reference

### 4. Customize catalog-info.yaml
```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-new-service           # This becomes your hostname
  description: My awesome service
  annotations:
    insureco.io/framework: express
spec:
  type: service
  lifecycle: production
  owner: my-org
  databases:
    - type: mongodb              # Add if you need a database
```

### 5. Run preflight
```bash
tawa preflight
```

### 6. Deploy
```bash
tawa deploy --watch               # Deploy to sandbox
# Verify at https://my-new-service.sandbox.tawa.insureco.io

tawa deploy --prod                # Deploy to production
```

## Monorepo Setup

For monorepos with multiple services:

```
my-monorepo/
  apps/
    frontend/
      catalog-info.yaml
      .tawa.yaml           # Points to shared Dockerfile, build context
    api/
      catalog-info.yaml
      .tawa.yaml
  helm/
    frontend/
    api/
  package.json
```

Each service's `.tawa.yaml`:
```yaml
dockerfile: Dockerfile
buildContext: ../..
helmChart: ../../helm/api
```

## Key Facts
- Every template comes with a pre-configured catalog-info.yaml
- The `metadata.name` field becomes your service hostname
- `spec.owner` is set automatically from your JWT when scaffolding
- You don't need a Dockerfile — the builder generates one from your framework annotation
- Run `tawa preflight` before your first deploy to catch config issues early