blackroad-operating-system/CLOUDFLARE_DNS_BLUEPRINT.md

☁️ CLOUDFLARE DNS BLUEPRINT

Multi-Domain DNS Configuration & Repo Responsibility Map

Version: 1.0 Date: 2025-11-18 Source: Extracted from MASTER_ORCHESTRATION_PLAN.md + ORG_STRUCTURE.md

---

EXECUTIVE SUMMARY

This document maps 10+ BlackRoad domains to:

• Cloudflare DNS records
• Repository ownership
• Deployment targets
• SSL configuration

DNS Strategy: Cloudflare nameservers (migrated from GoDaddy) for all domains SSL Strategy: Full (strict) with automatic SSL via Cloudflare + Railway/Vercel

---

PART 1: DOMAIN INVENTORY

Primary Domains (Phase 1)

Domain	Purpose	Owner Repo	Status	Phase
blackroad.systems	Corporate site	blackroad.io	🎯 Primary	1
blackroad.ai	Alias to OS	BlackRoad-Operating-System	Active	1
blackroad.network	Developer docs	BlackRoad-Operating-System	Planned	1
blackroad.me	Personal identity	BlackRoad-Operating-System	Planned	1

Secondary Domains (Phase 2)

Domain	Purpose	Owner Repo	Status	Phase
aliceqi.com	ALICE QI engine	lucidia / quantum-math-lab	Research	2
blackroadqi.com	Financial intelligence	blackroad-api (QI module)	Planned	2
lucidia.earth	Narrative experiences	lucidia	Development	2
blackroadquantum.com	Research hub	quantum-math-lab	Research	2

Tertiary Domains (Phase 3)

Domain	Purpose	Owner Repo	Status	Phase
roadwallet.com	Wallet service	BlackRoad-Operating-System	Alias	3
aliceos.io	Legacy alias	BlackRoad-Operating-System	Legacy	3
blackroadquantum.net	Quantum APIs	quantum-math-lab	Planned	3
blackroadquantum.info	Education hub	quantum-math-lab	Planned	3
blackroadquantum.store	Merch/courses	TBD (e-commerce repo)	Planned	3
lucidia.studio	Creative production	lucidia	Planned	3
blackroad.store	Community commerce	TBD (e-commerce repo)	Planned	3

---

PART 2: DNS RECORDS BY DOMAIN

blackroad.systems (Primary Corporate Site)

Zone ID: [Get from Cloudflare dashboard] Registrar: GoDaddy → Migrate nameservers to Cloudflare Owner Repo: blackboxprogramming/blackroad.io

DNS Records

Type	Name	Target	Proxy	TTL	Purpose	Responsible Repo
CNAME	@	cname.vercel-dns.com	✅	Auto	Corporate site	blackroad.io
CNAME	www	blackroad.systems	✅	Auto	www redirect	blackroad.io
CNAME	os	blackroad-os-production.up.railway.app	✅	Auto	OS interface	BlackRoad-Operating-System
CNAME	api	blackroad-api-production.up.railway.app	✅	Auto	API gateway	blackroad-api (Phase 2)
CNAME	prism	blackroad-prism-console.vercel.app	✅	Auto	Prism Console	blackroad-prism-console
CNAME	operator	blackroad-operator.up.railway.app	❌	Auto	Operator (internal)	blackroad-operator
CNAME	lucidia	lucidia-api.up.railway.app	✅	Auto	Lucidia API	lucidia
CNAME	docs	blackboxprogramming.github.io	✅	Auto	Developer docs	BlackRoad-Operating-System
TXT	@	v=spf1 include:_spf.google.com ~all	-	Auto	Email SPF	-
MX	@	1 aspmx.l.google.com	-	Auto	Email MX	-

Cloudflare Settings:

• SSL/TLS: Full (strict)
• Always Use HTTPS: Enabled
• Auto Minify: JavaScript, CSS, HTML
• Brotli: Enabled
• Cache Level: Standard

---

blackroad.ai (OS Alias)

Registrar: GoDaddy Owner Repo: blackboxprogramming/BlackRoad-Operating-System

DNS Records

Type	Name	Target	Proxy	Purpose	Responsible Repo
CNAME	@	os.blackroad.systems	✅	Alias to OS	BlackRoad-Operating-System
CNAME	www	blackroad.ai	✅	www redirect	BlackRoad-Operating-System

Page Rule:

blackroad.ai/*
  → Forwarding URL (301 - Permanent Redirect)
  → https://os.blackroad.systems/$1

---

blackroad.network (Developer Portal)

Registrar: GoDaddy Owner Repo: blackboxprogramming/BlackRoad-Operating-System (docs/ directory)

DNS Records

Type	Name	Target	Proxy	Purpose	Responsible Repo
CNAME	@	blackboxprogramming.github.io	✅	Developer docs	BlackRoad-Operating-System/docs/
CNAME	www	blackroad.network	✅	www redirect	BlackRoad-Operating-System/docs/
CNAME	api	blackroad-api-production.up.railway.app	✅	API for developers	blackroad-api

GitHub Pages Setup (in BlackRoad-Operating-System repo):

1. Enable GitHub Pages from docs/ directory
2. Add custom domain: blackroad.network
3. Enforce HTTPS
4. Cloudflare DNS points to GitHub Pages

---

blackroad.me (Personal Identity)

Registrar: GoDaddy Owner Repo: blackboxprogramming/BlackRoad-Operating-System

DNS Records

Type	Name	Target	Proxy	Purpose	Responsible Repo
CNAME	@	os.blackroad.systems	✅	Identity portal	BlackRoad-Operating-System
CNAME	www	blackroad.me	✅	www redirect	BlackRoad-Operating-System

Host-Based Routing (in BlackRoad-Operating-System):

# backend/app/middleware/domain_routing.py
from fastapi import Request

async def domain_middleware(request: Request, call_next):
    host = request.headers.get("host")

    if host == "blackroad.me":
        # Serve identity portal theme
        request.state.theme = "identity"

    response = await call_next(request)
    return response

---

lucidia.earth (Narrative Site)

Registrar: GoDaddy Owner Repo: blackboxprogramming/lucidia

DNS Records

Type	Name	Target	Proxy	Purpose	Responsible Repo
CNAME	@	lucidia-narrative.vercel.app	✅	Narrative site	lucidia
CNAME	www	lucidia.earth	✅	www redirect	lucidia
CNAME	api	lucidia-api.up.railway.app	✅	Lucidia API	lucidia

Phase 2 Launch (Month 12+)

---

aliceqi.com (ALICE QI Research)

Registrar: GoDaddy Owner Repo: blackboxprogramming/quantum-math-lab or lucidia-lab

DNS Records

Type	Name	Target	Proxy	Purpose	Responsible Repo
CNAME	@	aliceqi-research.vercel.app	✅	Research site	quantum-math-lab
CNAME	www	aliceqi.com	✅	www redirect	quantum-math-lab

Phase 2 Launch (Month 12+)

---

roadwallet.com (Wallet Alias)

Registrar: GoDaddy Owner Repo: blackboxprogramming/BlackRoad-Operating-System

DNS Records

Type	Name	Target	Proxy	Purpose	Responsible Repo
CNAME	@	os.blackroad.systems	✅	Alias to OS wallet	BlackRoad-Operating-System
CNAME	www	roadwallet.com	✅	www redirect	BlackRoad-Operating-System

Page Rule: Redirect to os.blackroad.systems#wallet (deep link to Wallet app)

---

aliceos.io (Legacy Alias)

Registrar: GoDaddy Owner Repo: blackboxprogramming/BlackRoad-Operating-System

DNS Records

Type	Name	Target	Proxy	Purpose	Responsible Repo
CNAME	@	os.blackroad.systems	✅	Legacy alias	BlackRoad-Operating-System
CNAME	www	aliceos.io	✅	www redirect	BlackRoad-Operating-System

Note: Consider deprecating or redirecting to blackroad.systems in Phase 2

---

PART 3: REPO RESPONSIBILITY MAP

Canonical Ownership Table

Subdomain / Domain	Repo	Service Type	Deployment Target	Phase
blackroad.systems	blackroad.io	Static site (Astro)	Vercel	1
os.blackroad.systems	BlackRoad-Operating-System	FastAPI + static UI	Railway	1
api.blackroad.systems	blackroad-api	FastAPI API	Railway	2
prism.blackroad.systems	blackroad-prism-console	React SPA	Vercel	2
operator.blackroad.systems	blackroad-operator	Worker service	Railway	2
lucidia.blackroad.systems	lucidia	FastAPI AI service	Railway	1/2
docs.blackroad.systems	BlackRoad-Operating-System	GitHub Pages (docs/)	GitHub Pages	1
blackroad.network	BlackRoad-Operating-System	GitHub Pages (docs/)	GitHub Pages	1
blackroad.me	BlackRoad-Operating-System	Identity portal	Railway	1
lucidia.earth	lucidia	Narrative site	Vercel	2
aliceqi.com	quantum-math-lab	Research site	Vercel	2

---

PART 4: CLOUDFLARE MIGRATION CHECKLIST

Per-Domain Migration (Repeat for all domains)

Step 1: Add Domain to Cloudflare

• Log in to Cloudflare dashboard
• Click "Add a site"
• Enter domain (e.g., blackroad.systems)
• Choose Free plan
• Cloudflare scans existing DNS records from GoDaddy
• Review imported records, add missing ones

Step 2: Update Nameservers

• Cloudflare provides 2 nameservers (e.g., aaaa.ns.cloudflare.com, bbbb.ns.cloudflare.com)
• Log in to GoDaddy
• Go to domain → Manage DNS → Nameservers
• Switch from GoDaddy to Custom
• Enter Cloudflare nameservers
• Save (propagation: 5-60 minutes)

Step 3: Verify Active

• Wait for Cloudflare to detect nameserver change
• Cloudflare dashboard should say "Active" (not "Pending")
• Test DNS resolution: dig blackroad.systems (should show Cloudflare IPs)

Step 4: Configure SSL

• Cloudflare → SSL/TLS → Set to "Full (strict)"
• SSL/TLS → Edge Certificates → Enable "Always Use HTTPS"
• SSL/TLS → Edge Certificates → Enable "Automatic HTTPS Rewrites"

Step 5: Configure Performance

• Speed → Optimization → Enable Auto Minify (JS, CSS, HTML)
• Speed → Optimization → Enable Brotli
• Caching → Configuration → Cache Level: Standard

Step 6: Test

• Visit https://yourdomain.com → Should load with 🔒
• Visit http://yourdomain.com → Should redirect to HTTPS
• Test API: curl https://os.blackroad.systems/health

Domains to Migrate (Priority Order)

Week 1:

1. blackroad.systems (corporate site - highest priority)
2. blackroad.ai (OS alias)
3. blackroad.me (identity)

Week 2: 4. [ ] blackroad.network (developer docs) 5. [ ] roadwallet.com (wallet alias)

Phase 2 (Month 12+): 6. [ ] lucidia.earth 7. [ ] aliceqi.com 8. [ ] blackroadqi.com 9. [ ] blackroadquantum.com

---

PART 5: AUTOMATION SCRIPTS

DNS Sync Script (Planned)

File: scripts/cloudflare/sync_dns.py

#!/usr/bin/env python3
"""
Sync DNS records from config to Cloudflare
Usage: python scripts/cloudflare/sync_dns.py --domain blackroad.systems
"""

import os
import yaml
import requests
from typing import Dict, List

CF_API_TOKEN = os.getenv("CF_API_TOKEN")
CF_ZONE_ID = os.getenv("CF_ZONE_ID")

def load_config(domain: str) -> Dict:
    """Load DNS config from ops/domains/{domain}.yaml"""
    with open(f"ops/domains/{domain}.yaml") as f:
        return yaml.safe_load(f)

def get_existing_records(zone_id: str) -> List[Dict]:
    """Fetch existing DNS records from Cloudflare"""
    url = f"https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records"
    headers = {"Authorization": f"Bearer {CF_API_TOKEN}"}
    response = requests.get(url, headers=headers)
    return response.json()["result"]

def create_dns_record(zone_id: str, record: Dict):
    """Create DNS record in Cloudflare"""
    url = f"https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records"
    headers = {
        "Authorization": f"Bearer {CF_API_TOKEN}",
        "Content-Type": "application/json"
    }
    response = requests.post(url, headers=headers, json=record)
    return response.json()

def update_dns_record(zone_id: str, record_id: str, record: Dict):
    """Update existing DNS record"""
    url = f"https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records/{record_id}"
    headers = {
        "Authorization": f"Bearer {CF_API_TOKEN}",
        "Content-Type": "application/json"
    }
    response = requests.put(url, headers=headers, json=record)
    return response.json()

def sync_domain(domain: str):
    """Sync DNS records for a domain"""
    print(f"Syncing DNS for {domain}...")

    config = load_config(domain)
    existing = get_existing_records(CF_ZONE_ID)

    for record in config["dns_records"]:
        # Check if record exists
        existing_record = next((r for r in existing if r["name"] == record["name"] and r["type"] == record["type"]), None)

        if existing_record:
            print(f"  Updating {record['type']} {record['name']}")
            update_dns_record(CF_ZONE_ID, existing_record["id"], record)
        else:
            print(f"  Creating {record['type']} {record['name']}")
            create_dns_record(CF_ZONE_ID, record)

    print(f"✅ Sync complete for {domain}")

if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument("--domain", required=True)
    args = parser.parse_args()

    sync_domain(args.domain)

Config File Example (ops/domains/blackroad.systems.yaml):

domain: blackroad.systems
zone_id: your-zone-id

dns_records:
  - type: CNAME
    name: "@"
    content: cname.vercel-dns.com
    proxied: true
    ttl: 1  # Auto

  - type: CNAME
    name: www
    content: blackroad.systems
    proxied: true
    ttl: 1

  - type: CNAME
    name: os
    content: blackroad-os-production.up.railway.app
    proxied: true
    ttl: 1

  # ... more records

Usage:

export CF_API_TOKEN="your-token"
export CF_ZONE_ID="your-zone-id"

python scripts/cloudflare/sync_dns.py --domain blackroad.systems

---

PART 6: MONITORING & HEALTH CHECKS

Domain Health Check Workflow

File: .github/workflows/domain-health.yml

name: Domain Health
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  workflow_dispatch:

jobs:
  health:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        domain:
          - https://blackroad.systems
          - https://os.blackroad.systems
          - https://api.blackroad.systems
          - https://prism.blackroad.systems
          - https://blackroad.network
    steps:
      - name: Check ${{ matrix.domain }}
        run: |
          STATUS=$(curl -s -o /dev/null -w "%{http_code}" ${{ matrix.domain }}/health || echo "000")
          if [ "$STATUS" != "200" ]; then
            echo "❌ ${{ matrix.domain }} is down (status: $STATUS)"
            exit 1
          else
            echo "✅ ${{ matrix.domain }} is up"
          fi

      - name: Check SSL
        run: |
          echo | openssl s_client -servername $(echo ${{ matrix.domain }} | sed 's/https:\/\///') -connect $(echo ${{ matrix.domain }} | sed 's/https:\/\///'):443 2>/dev/null | openssl x509 -noout -dates

---

PART 7: COST SUMMARY

Cloudflare Costs

Free Tier (all Phase 1 domains):

• Unlimited DNS queries
• SSL certificates (automatic)
• DDoS protection (unmetered)
• CDN caching (100 GB/month)
• 3 Page Rules per domain

Pro Tier ($20/mo per domain, if needed):

• More Page Rules
• Image optimization
• Mobile redirect
• Polish (WebP/AVIF)

Recommendation: Stay on Free tier for Phase 1

GoDaddy Costs

Domain Registration (annual):

• .systems: ~$15/year
• .com: ~$12/year
• .ai: ~$90/year (premium TLD)
• .earth: ~$20/year
• .me: ~$20/year
• .io: ~$40/year

Total Annual: ~$200-300/year for all domains

DNS Hosting: $0 (migrated to Cloudflare)

---

CONCLUSION

Current State: Domains registered with GoDaddy, DNS managed by GoDaddy Target State: Domains registered with GoDaddy, DNS managed by Cloudflare Migration Effort: 1-2 days for Phase 1 domains

Next Action: Start with blackroad.systems migration (see NEXT_ACTIONS_ALEXA.md, Item #1)

---

Last Updated: 2025-11-18 Next Review: After Phase 1 DNS migration complete (Week 2)