blackroad-os-archive/CONNECTION_MAP.md

🗺️ BlackRoad OS — Full Connection & Integration Mapping

Last updated: 2025-11-24
Purpose: Create a unified source-of-truth for all connections across infra, repos, domains, deployments, DNS, and credentials.
Use: Feed into Codex to generate corrections, workflows, infra fixes, DNS patches, and GitHub automation.

---

0. Overview

Document captures every active endpoint, domain, repository, cloud service, and integration path.

Sections

1. Cloudflare
2. Domains & DNS
3. Railway Deployments
4. Vercel Deployments
5. GitHub Org & Repos
6. DigitalOcean
7. Stripe
8. Google Workspace
9. USPTO & Trademark infra
10. Agents & Automations layer
11. Error States / Fix Queue
12. Codex Prompt Templates

---

1. Cloudflare (dash.cloudflare.com)

Tabs found:

• Pages: blackroad-os-ideas
• Workers & Pages Upload
• Primary domain management for blackroad.io and others

1.1 Cloudflare Zones

• blackroad.io → status: 521
• blackroad.systems → TODO: map subdomains
• blackroad.me → placeholder
• blackroad.network
• blackroadai.com
• (List all domains owned in GoDaddy and paste here after the next step.)

1.2 Cloudflare DNS (per domain)

Use this template for each domain:

Domain: <domain>
Apex Root (@):
    CNAME → <target> (Railway/Vercel)
    Proxy: ON/OFF
www:
    CNAME → <target>
Subdomains:
    <sub> → <cloud-service>
TLS Mode:
    <Flexible / Full / Full Strict>
Workers Routes:
    <route pattern> → <worker>
Pages Bindings:
    <project> → <repo> → <deployment>

---

2. Domains (GoDaddy)

Source tab: https://account.godaddy.com/products

Document all domains you own and their authoritative DNS host (Cloudflare, GoDaddy, Vercel).

Domain: <domain>
Registrar: GoDaddy
DNS Managed At: <Cloudflare / GoDaddy / Vercel>
Connected Services:
    - Website: <URL>
    - API: <URL>
    - Subdomains: <map from Cloudflare section>
Renewal Date: <date>

---

3. Railway Deployments (railway.com)

Open tabs:

• Project: railway-blackroad-os
• Dashboard
• Error page: blackroad-os-operator-production.up.railway.app (500/521)

Service: <railway service name>
Environment: <production / staging>
Public URL: <*.up.railway.app>
Custom Domain: <domain/subdomain>
Bound Variables:
    - PORT:
    - API_URL:
    - DB_URL:
Health:
    /health endpoint → <working / failing>
Error States:
    <from logs>

---

4. Vercel (vercel.com)

Project: <project name>
Framework: <Next.js/Static>
Production Domain: <domain>
Preview: <vercel.app URL>
Connected Repo: <GitHub repo>
Environment Variables:
    <list of keys>
Build Status:
    <success/fail/reason>

---

5. GitHub Organization (BlackRoad OS)

Open tabs:

• Org listing
• Repo list (24 repos)
• Teams setup earlier

Repo: <repo name>
Purpose: <one-liner>
Connected Services:
    - Railway: <service>
    - Vercel: <project>
    - Cloudflare Pages: <site>
    - DigitalOcean: <droplet>
Deploy Targets:
    main → <production>
    dev → <staging>
    feature/* → <preview>
Workflows:
    - build.yml: <status>
    - tests.yml: <status>
Permissions:
    Team: <team name> (read/write/admin)
Branch Rules:
    <rules>

---

6. DigitalOcean (Droplets)

Source tab: cloud.digitalocean.com/droplets

Droplet: <name>
IP: <ip>
Purpose: <service>
Connected Domain: <domain>
Ports:
    80: <service>
    443: <service>
Deployments:
    <agent/scheduler/service>

---

7. Stripe (dashboard)

Stripe Account: BlackRoad OS, Inc.
Verification:
    Status: <pending/resolved>
    Required Docs: <list>
Connected Domains:
    - Login: <domain>
    - Webhooks: <url>
Environment:
    Test Keys: <present/not>
    Live Keys: <present/not>

---

8. Google Workspace

Status: Pending signup
Chosen Domain: <domain>
MX Records Needed:
    - ASPMX.L.GOOGLE.COM
    - ALT1.ASPMX.L.GOOGLE.COM
    - ALT2.ASPMX.L.GOOGLE.COM
    - ALT3.ASPMX.L.GOOGLE.COM
    - ALT4.ASPMX.L.GOOGLE.COM
DNS Applied In: <Cloudflare/GoDaddy>
SPF: v=spf1 include:_spf.google.com ~all
DMARC: <record>

---

9. USPTO & Trademark Infra

Open tabs:

• TSDR
• TM search
• Fees portal

Trademark: <mark>
Serial: <number>
Status: <LIVE / DEAD / Office Action / Pending>
Classes:
    <class list>
Renewals:
    <dates needed>
Connection to BlackRoad Infra:
    - Branding in repos
    - Website claims

---

10. Agents & Automations Mapping

Agent Name: <name>
Repo Home: <repo>
Runtime: <railway/vercel/do>
Endpoints:
    /health
    /v1/<task>
Connected Data:
    - Postgres: <url>
    - Redis: <url>
GitHub Workflows:
    - <workflow name>
Secrets:
    <GitHub secrets key list>

---

11. Error State Queue

Current known issues:

• blackroad.io → 521 Web server is down
• blackroad-os-operator-production → error page
• Missing DNS between Cloudflare and Railway
• Missing Pages deployments
• Vercel projects not connected to repos
• GitHub repos missing .github/workflows
• Railway health endpoints missing

---

12. Codex Prompt Templates

12.1 DNS Fix Prompt

Codex: Map domain <domain> to <target>.
Create CNAME @ or A records as needed.
Ensure proxy = <on/off>.
Enable Full SSL.

12.2 Railway Fix Prompt

Codex: Verify /health on <service>.
If failing, scaffold minimal FastAPI app with /health.
Push to repo <repo>.
Deploy automatically via Railway.

12.3 GitHub Workflow Fix Prompt

Codex: Add CI/CD workflow to <repo>.
Steps:
  - install deps
  - run tests
  - deploy to Railway/Vercel

12.4 Cloudflare Pages Fix Prompt

Codex: Deploy <repo> as Cloudflare Pages project <name>.
Bind to <domain>.

---

13. Export Options

• Push to repo: Drop this file into the target repo (e.g., blackroad-os-infra/CONNECTION_MAP.md).
• Convert to Google Doc: Export with structured headings for quick sharing across teams.