Merge branch origin/codex/create-master-connection-mapping-document into main
This commit is contained in:
Alexa Amundson
299
CONNECTION_MAP.md
Normal file
299
CONNECTION_MAP.md
Normal file
@@ -0,0 +1,299 @@
|
|||||||
|
# 🗺️ 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.
|
||||||
Reference in New Issue
Block a user