Tawa Platform

About

The foundational skill that gives AI agents a mental map of the Tawa platform. Covers all platform services (Bio-ID, Koko, Janus, Builder, Wallet), their purposes, how they communicate via Kubernetes DNS, and the external URL patterns for each environment.

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# Tawa Platform

## What this skill covers
The architecture of the Tawa platform — what services exist, how they connect, and the URLs you need.

## Platform Services

| Service | Purpose | Production URL |
|---------|---------|----------------|
| **Bio-ID** | Identity & OAuth provider | https://bio.tawa.insureco.io |
| **Koko** | Service registry & API gateway | Internal (cluster DNS) |
| **Janus** | Health monitoring & gas metering | Internal (cluster DNS) |
| **iec-builder** | Build pipeline & deployment | https://builder.tawa.insureco.io |
| **iec-wallet** | Token wallet & gas reserve | Internal (cluster DNS) |
| **Forgejo** | Git hosting (alternative to GitHub) | https://git.tawa.insureco.io |
| **tawa-web** | Platform console & docs | https://tawa.insureco.io |

## How Services Connect

```
Developer -> tawa CLI -> iec-builder
                            |
                +-----------+-----------+
                |           |           |
             Bio-ID      Koko       Cloudflare
          (OAuth)    (Registry)     (DNS)
                            |
                       Kubernetes
                      (Helm deploy)
                            |
                  +---------+---------+
                  |         |         |
               Janus     Wallet    Your Service
            (Metrics)   (Gas)     (Running pod)
```

## Internal Service URLs (Kubernetes DNS)

Services communicate inside the cluster using this pattern:
```
http://{service}.{service}-{environment}.svc.cluster.local:{port}
```

Examples:
- `http://iec-wallet.iec-wallet-prod.svc.cluster.local:3000`
- `http://koko-iec-koko.koko-prod.svc.cluster.local:3001`
- `http://janus.janus-prod.svc.cluster.local:3000`

## External URL Patterns

| Environment | Pattern | Example |
|-------------|---------|---------|
| Sandbox | `{service}.sandbox.tawa.insureco.io` | my-api.sandbox.tawa.insureco.io |
| Production | `{service}.tawa.insureco.io` | my-api.tawa.insureco.io |
| UAT | `{service}.uat.tawa.insureco.io` | my-api.uat.tawa.insureco.io |

## Key Facts
- All deployments go through `tawa deploy` — the builder handles everything
- OAuth is auto-provisioned via Bio-ID on every deploy
- Databases are declared in catalog-info.yaml and provisioned automatically
- Gas tokens pay for hosting and API calls (1 token = $0.01 USD)
- Services register in Koko automatically on first deploy
- DNS is managed via Cloudflare automatically

Install

Copy the skill content and save it to:

~/.claude/rules/tawa-platform.md

Details

Format

Rule

Category

platform

Version

1.0.0

Tokens

~800

Updated

2026-02-13