# DNS Management (Cloudflare)

**Last Updated:** 2026-01
**Confidence:** High

## Summary

DNS for threesix.ai domains is managed via Cloudflare API. Projects get auto-generated subdomains on creation, and users can add custom subdomains or external domain aliases. The Cloudflare adapter implements the `DNSProvider` port interface.

**Key Facts:**
- Auto-provisioned subdomains: `{random}.threesix.ai` created on project creation
- Custom subdomains: User-chosen `{name}.threesix.ai` auto-configured via API
- External aliases: User manages DNS, rdev only configures ingress
- Credentials: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ZONE_ID` in `.secrets` → loaded to PostgreSQL

**Credential Keys:** `internal/domain/credential.go:23-24`

## Domain Types

| Type | Example | Auto-DNS |
|------|---------|----------|
| `primary_auto` | `k7m2x9p4.threesix.ai` | Yes |
| `primary_custom` | `my-app.threesix.ai` | Yes |
| `alias` | `www.myapp.com` | No |

## Architecture

**Port Interface:** `internal/port/dns_provider.go`
```
CreateRecord, UpdateRecord, UpsertRecord, DeleteRecord
DeleteRecordByName, GetRecord, ListRecords, FindRecord
```

**Adapter:** `internal/adapter/cloudflare/client.go`
- Uses Cloudflare API v4 with Bearer token auth
- 3-attempt retry on UpsertRecord for race conditions
- Auto-normalizes subdomain names

**Service:** `internal/service/project_infra_domains.go`
- AddDomain, RemoveDomain, ListDomains, GetPrimaryDomain
- Coordinates between Cloudflare, database, and K8s ingress

**Handler:** `internal/handlers/infrastructure_domains.go`
- REST endpoints: GET/POST/DELETE `/projects/{id}/domains`

## Database Schema

**Table:** `project_domains`
- `project_id` UUID → cascade delete
- `domain` VARCHAR(255) UNIQUE
- `type` CHECK (primary_auto|primary_custom|alias)
- `dns_record_id` VARCHAR(64) - Cloudflare record ID for cleanup
- `verified` BOOLEAN

## API Endpoints

```
GET    /projects/{id}/domains           - List all domains
POST   /projects/{id}/domains           - Add domain
DELETE /projects/{id}/domains/{domain}  - Remove domain
```

## Related Topics

- [Infrastructure Management](../features/infrastructure.md) - Broader infra context
- [Credentials Guide](../../.claude/guides/ops/credentials.md) - Loading secrets