Tawa Platform

About

The architecture of the Tawa platform — what services exist, how they connect, and the URLs you need.

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.pro |
| **Koko** | Service registry & API gateway | Internal (cluster DNS) |
| **Janus** | Health monitoring & gas metering | Internal (cluster DNS) |
| **iec-builder** | Build pipeline & deployment | https://builder.tawa.pro |
| **iec-wallet** | Token wallet & gas reserve | Internal (cluster DNS) |
| **Forgejo** | Git hosting (alternative to GitHub) | https://git.tawa.pro |
| **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.pro` | my-api.sandbox.tawa.pro |
| Production | `{service}.tawa.pro` | my-api.tawa.pro |
| UAT | `{service}.uat.tawa.pro` | my-api.uat.tawa.pro |

## Organization Identity

Organizations have two identifiers managed by Bio-ID:

| Identifier | Format | Example | Used by |
|-----------|--------|---------|---------|
| **orgId** | `ORG-{timestamp}{random}` | `ORG-1771475158MOH5U2` | Bio-ID admin APIs (departments, roles) |
| **orgSlug** | URL-friendly slug | `insureco` | catalog-info.yaml `spec.owner`, wallet IDs, Koko, Builder, Forgejo |

- **Wallet IDs**: `wallet-{orgSlug}` (e.g., `wallet-insureco`)
- **Bio-ID JWTs**: carry both `orgId` (ORG-xxx) and `orgSlug` (slug) in the payload
- **tawa CLI**: extracts `orgSlug` for `spec.owner` scaffolding (never uses ORG-xxx for owner)
- **Organization.resolve()**: Bio-ID static method that accepts ORG-xxx, ObjectId, or slug

## 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.26825

Tokens

~773

Updated

2026-06-24