From d0979b6c44889f5d2f27cc81678ba541828b7d3f Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Nov 2025 01:57:46 +0000 Subject: [PATCH] Add BlackRoad Master Orchestration Plan and infrastructure blueprints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit implements the complete "master orchestration prompt" deliverables: ## New Documentation ### Master Plan - MASTER_ORCHESTRATION_PLAN.md - Complete infrastructure → product → ecosystem blueprint - Full stack architecture (Layer 1-7) - Cloudflare → GoDaddy → Railway → GitHub topology - Agent orchestration model (Atlas → Operator → Prism → Lucidia) - 3-phase execution roadmap - Atlas automation commands ### Infrastructure - infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md - Complete DNS configuration - Migration process (GoDaddy → Cloudflare) - DNS records for all 10+ domains - SSL/TLS configuration - Caching rules and security headers - Automation scripts - Troubleshooting guide ### GitHub Organization - .github/GITHUB_ENTERPRISE_SETUP.md - Repository organization structure - Monorepo vs multi-repo strategy - Branch protection rules - Required status checks - PR/issue templates - Project boards and labels - Recommended workflow additions (CodeQL, Dependabot) - .github/CODEOWNERS - Code ownership definitions - Global owners - Component-specific owners (backend, frontend, infra, docs) ### Next Actions - NEXT_ACTIONS_ALEXA.md - No-overwhelm execution checklist - Immediate priorities (infrastructure setup) - Week 1-2 tasks (product polish) - Week 3-4 tasks (alpha launch) - Success metrics - Tools & resources ## Context These documents synthesize: - The Big Kahuna Vision (complete OS architecture) - 3-phase execution roadmap (18-24 months) - Brand architecture (multi-brand ecosystem) - Current monorepo structure - Infrastructure topology ## Purpose Provide Alexa (Operator) with: 1. Complete infrastructure blueprint 2. Clear execution path 3. No-overwhelm next steps 4. Reference for all future decisions ## Next Steps See NEXT_ACTIONS_ALEXA.md for immediate priorities: 1. Migrate DNS to Cloudflare 2. Verify Railway deployment 3. Update GitHub secrets 4. Polish OS and add real backend data 5. Launch blackroad.systems and docs sites --- Ready for the next command, Operator. --- .github/CODEOWNERS | 47 + .github/GITHUB_ENTERPRISE_SETUP.md | 736 ++++++++++++ MASTER_ORCHESTRATION_PLAN.md | 1074 ++++++++++++++++++ NEXT_ACTIONS_ALEXA.md | 482 ++++++++ infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md | 523 +++++++++ 5 files changed, 2862 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/GITHUB_ENTERPRISE_SETUP.md create mode 100644 MASTER_ORCHESTRATION_PLAN.md create mode 100644 NEXT_ACTIONS_ALEXA.md create mode 100644 infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..b973200 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,47 @@ +# BlackRoad OS Code Owners +# This file defines who is responsible for code in this repository. +# Each line is a file pattern followed by one or more owners. + +# Global owners (all files) +* @alexa-amundson + +# Backend +/backend/ @alexa-amundson +/backend/app/ @alexa-amundson +/backend/requirements.txt @alexa-amundson +/backend/Dockerfile @alexa-amundson + +# Frontend / OS +/blackroad-os/ @alexa-amundson +/backend/static/ @alexa-amundson + +# Infrastructure & DevOps +/.github/ @alexa-amundson +/.github/workflows/ @alexa-amundson +/scripts/ @alexa-amundson +/ops/ @alexa-amundson +/infra/ @alexa-amundson +railway.toml @alexa-amundson +railway.json @alexa-amundson +docker-compose.yml @alexa-amundson + +# Documentation +/docs/ @alexa-amundson +/README.md @alexa-amundson +/*.md @alexa-amundson + +# Python SDK +/sdk/python/ @alexa-amundson + +# TypeScript SDK +/sdk/typescript/ @alexa-amundson + +# Agents & Prompts +/agents/ @alexa-amundson +/blackroad-universe/prompts/ @alexa-amundson + +# Cognitive & Research +/cognitive/ @alexa-amundson + +# BlackRoad Universe (Brand, GTM, Domains) +/blackroad-universe/ @alexa-amundson diff --git a/.github/GITHUB_ENTERPRISE_SETUP.md b/.github/GITHUB_ENTERPRISE_SETUP.md new file mode 100644 index 0000000..1d65f77 --- /dev/null +++ b/.github/GITHUB_ENTERPRISE_SETUP.md @@ -0,0 +1,736 @@ +# GitHub Enterprise Structure +## Repository Organization, Policies, and Workflows + +**Version:** 1.0 +**Date:** 2025-11-18 +**Purpose:** Define GitHub organization structure and best practices + +--- + +## Repository Strategy + +### Current State: Monorepo ✅ + +**Repository**: `blackboxprogramming/BlackRoad-Operating-System` + +**Structure**: +``` +BlackRoad-Operating-System/ +├── backend/ # FastAPI backend +├── blackroad-os/ # Win95 OS frontend +├── docs/ # Documentation +├── sdk/ # Python & TypeScript SDKs +│ ├── python/ +│ └── typescript/ +├── agents/ # Agent specifications +├── cognitive/ # Cognitive architecture +├── blackroad-universe/ # Brand, domains, GTM +├── ops/ # Operations, domain config +├── infra/ # Infrastructure configs +└── scripts/ # Automation scripts +``` + +**Pros**: +- ✅ Single source of truth +- ✅ Atomic commits across frontend/backend +- ✅ Simpler for small teams +- ✅ Easier local development + +**Cons**: +- ❌ Larger repo size +- ❌ Harder to scale teams (can't assign granular permissions) +- ❌ All CI runs even if only one component changes (can be mitigated with path filters) + +**Recommendation**: **Keep monorepo for Phase 1** (0-12 months), evaluate split in Phase 2 when team grows. + +--- + +### Future State: Multi-Repo (Phase 2+) + +**When to split**: +- Team size > 10 engineers +- Need granular access control (different teams own different repos) +- Want independent release cycles (frontend vs backend) + +**Proposed Repos**: + +1. **blackroad-os-core** - Core OS runtime, identity (PS-SHA∞) + - Owner: Core team + - Language: Python, JavaScript + - Deploy: Railway + +2. **blackroad-os-prism-console** - Admin, observability, Prism UI + - Owner: Frontend team + - Language: React/TypeScript + - Deploy: Vercel / GitHub Pages + +3. **blackroad-os-operator** - Workers, schedulers, agent orchestration + - Owner: Backend team + - Language: Python (Celery/RQ) + - Deploy: Railway + +4. **blackroad-os-api** - Backend API gateway, routing, schemas + - Owner: Backend team + - Language: Python (FastAPI) + - Deploy: Railway + +5. **blackroad-os-web** - Pocket OS web interface (frontend) + - Owner: Frontend team + - Language: HTML/CSS/JS + - Deploy: GitHub Pages + +6. **blackroad-os-docs** - Codex, specs, standards, whitepapers + - Owner: Docs team + - Language: Markdown + - Deploy: GitHub Pages + +--- + +## GitHub Organization + +### Organization Settings + +**Name**: `blackroad` (preferred) or keep `blackboxprogramming` + +**Teams**: + +| Team | Role | Members | Repositories | +|------|------|---------|--------------| +| `@blackroad/core` | Maintain | Alexa + core contributors | All repos (admin) | +| `@blackroad/backend` | Write | Backend engineers | backend, api, operator repos | +| `@blackroad/frontend` | Write | Frontend engineers | web, prism-console repos | +| `@blackroad/docs` | Write | Docs writers, technical writers | docs repo | +| `@blackroad/community` | Triage | External contributors | All (read, can create issues/PRs) | + +**Team Sync** (if using external tools): +- Sync with Slack: `#blackroad-core`, `#blackroad-backend`, etc. +- Sync with Discord: Roles mirror GitHub teams + +--- + +## Branch Protection Rules + +### `main` Branch (Production) + +**Required Settings**: +- ✅ **Require pull request before merging** + - Required approvals: **1** + - Dismiss stale reviews: ✅ + - Require review from Code Owners: ✅ + +- ✅ **Require status checks to pass** + - Required checks: + - `CI / lint` + - `CI / type-check` + - `CI / test-backend` + - `CI / build` + - Require branches to be up to date: ✅ + +- ✅ **Require conversation resolution before merging** + +- ❌ **Do not allow bypassing** (enforce for administrators) + +- ❌ **Do not allow force pushes** + +- ❌ **Do not allow deletions** + +**Linear History**: +- ✅ Require linear history (or use squash merging) + +--- + +### `develop` Branch (If Using GitFlow) + +**Optional Settings**: +- ✅ Require pull request +- ✅ Require status checks +- ✅ **Allow force pushes** (for rebasing - use with caution) +- Approvals: 0-1 (more flexible than `main`) + +--- + +### `claude/*` Branches (AI Agent Branches) + +**Special Settings**: +- ✅ Allow direct commits (AI agents commit directly) +- ✅ Require status checks to pass +- ❌ No protection rules (temporary branches, auto-deleted after PR merge) + +**Naming Convention**: +- `claude/feature-name-{session-id}` +- Session ID ensures unique branch names per AI session + +--- + +## Required Status Checks + +### Current Workflows + +From `.github/workflows/`: + +| Workflow | File | Triggers | Required Checks | +|----------|------|----------|----------------| +| **CI** | `ci.yml` | Push to `main`, PR | `lint`, `type-check`, `build` | +| **Backend Tests** | `backend-tests.yml` | Push to `backend/**`, PR | `test-backend` | +| **Railway Deploy** | `railway-deploy.yml` | Push to `main` | (deployment only, not blocking) | +| **GitHub Pages Deploy** | `deploy.yml` | Push to `main` | (deployment only) | +| **Railway Secrets Audit** | `railway-automation.yml` | Schedule (nightly) | (audit only) | +| **Domain Sync** | `sync-domains.yml` | Manual, schedule | (sync only) | +| **Domain Health** | `domain-health.yml` | Schedule (hourly) | (monitoring only) | + +### Adding Checks to Branch Protection + +**Via GitHub UI**: +1. Go to Settings → Branches → Branch protection rules +2. Click `main` (or create new) +3. Under "Require status checks to pass before merging": + - ✅ Require status checks + - Search and add: `CI / lint`, `CI / type-check`, `CI / test-backend`, `CI / build` + - ✅ Require branches to be up to date + +**Via GitHub API** (automation): + +```bash +gh api \ + --method PUT \ + -H "Accept: application/vnd.github+json" \ + /repos/blackboxprogramming/BlackRoad-Operating-System/branches/main/protection \ + -f required_status_checks='{"strict":true,"contexts":["CI / lint","CI / type-check","CI / test-backend","CI / build"]}' \ + -f enforce_admins=false \ + -f required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \ + -f restrictions=null \ + -f required_conversation_resolution=true +``` + +--- + +## CODEOWNERS File + +**Location**: `.github/CODEOWNERS` + +**Already Created**: See `.github/CODEOWNERS` in this repo + +**How it Works**: +- When PR changes files, GitHub auto-requests review from owners +- PR can't merge until Code Owner approves (if "Require review from Code Owners" is enabled) + +--- + +## Pull Request Templates + +**Location**: `.github/PULL_REQUEST_TEMPLATE.md` + +```markdown +## Description + + +## Type of Change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Infrastructure change + +## Related Issue + + +## Testing + +- [ ] Tested locally +- [ ] Added/updated unit tests +- [ ] Added/updated integration tests +- [ ] Tested in staging environment + +## Screenshots (if applicable) + + +## Checklist +- [ ] Code follows the project's style guidelines +- [ ] Self-review of code completed +- [ ] Comments added for complex logic +- [ ] Documentation updated (if needed) +- [ ] No new warnings generated +- [ ] Tests pass locally +- [ ] Related documentation updated + +## Deployment Notes + +``` + +**Create file**: `.github/PULL_REQUEST_TEMPLATE.md` with above content + +--- + +## Issue Templates + +**Location**: `.github/ISSUE_TEMPLATE/` + +### 1. Bug Report + +**File**: `.github/ISSUE_TEMPLATE/bug_report.md` + +```markdown +--- +name: Bug Report +about: Report a bug in BlackRoad OS +title: "[BUG] " +labels: bug +assignees: '' +--- + +## Bug Description + + +## Steps to Reproduce +1. Go to '...' +2. Click on '...' +3. Scroll down to '...' +4. See error + +## Expected Behavior + + +## Actual Behavior + + +## Environment +- **BlackRoad OS Version**: [e.g., v0.1.1] +- **Browser**: [e.g., Chrome 120, Safari 17] +- **OS**: [e.g., macOS 14, Windows 11, iOS 17] +- **Device**: [e.g., Desktop, iPhone 15] + +## Screenshots + + +## Additional Context + + +## Possible Solution + +``` + +### 2. Feature Request + +**File**: `.github/ISSUE_TEMPLATE/feature_request.md` + +```markdown +--- +name: Feature Request +about: Suggest a new feature for BlackRoad OS +title: "[FEATURE] " +labels: enhancement +assignees: '' +--- + +## Feature Description + + +## Problem Statement + + +## Proposed Solution + + +## Alternatives Considered + + +## Additional Context + + +## Acceptance Criteria + +- [ ] Criterion 1 +- [ ] Criterion 2 +``` + +### 3. Documentation + +**File**: `.github/ISSUE_TEMPLATE/documentation.md` + +```markdown +--- +name: Documentation +about: Suggest documentation improvements +title: "[DOCS] " +labels: documentation +assignees: '' +--- + +## Documentation Issue + + +## Affected Pages/Sections + + +## Suggested Changes + + +## Additional Context + +``` + +**Create these files** in `.github/ISSUE_TEMPLATE/` + +--- + +## Project Boards + +### Org-Level Project Board + +**Name**: "BlackRoad OS Roadmap" + +**View Type**: Board + +**Columns**: + +| Column | Description | Automation | +|--------|-------------|------------| +| 📋 Backlog | All new issues, not yet prioritized | Auto-add: new issues | +| 🎯 Phase 1 (Prove the OS) | Q1-Q4 deliverables | Auto-add: label `Phase 1` | +| 🚀 Phase 2 (Expand Intelligence) | Q5-Q6 deliverables | Auto-add: label `Phase 2` | +| 🌍 Phase 3 (Ecosystem) | Q7-Q8 deliverables | Auto-add: label `Phase 3` | +| 🏃 In Progress | Currently being worked on | Auto-add: assigned + status `in progress` | +| 👀 In Review | PR submitted, awaiting review | Auto-add: PR opened | +| ✅ Done | Completed | Auto-add: PR merged, issue closed | + +**Automation Rules**: +- Issue created → add to "Backlog" +- Issue labeled `Phase 1` → move to "Phase 1" column +- Issue assigned → move to "In Progress" +- PR opened → move to "In Review" +- PR merged → move to "Done" +- Issue closed → move to "Done" + +**Create via GitHub UI**: +1. Go to Organization → Projects → New project +2. Choose "Board" template +3. Add columns above +4. Configure automation (Settings → Workflows) + +--- + +## Labels + +**Standard Labels** (auto-created by GitHub): + +| Label | Color | Description | +|-------|-------|-------------| +| `bug` | Red | Something isn't working | +| `documentation` | Blue | Improvements or additions to documentation | +| `duplicate` | Gray | This issue or PR already exists | +| `enhancement` | Green | New feature or request | +| `good first issue` | Purple | Good for newcomers | +| `help wanted` | Orange | Extra attention is needed | +| `invalid` | Gray | This doesn't seem right | +| `question` | Pink | Further information is requested | +| `wontfix` | White | This will not be worked on | + +**Custom Labels** (add these): + +| Label | Color | Description | +|-------|-------|-------------| +| `Phase 1` | `#0E8A16` | Phase 1: Prove the OS (Months 0-12) | +| `Phase 2` | `#1D76DB` | Phase 2: Expand Intelligence (Months 12-18) | +| `Phase 3` | `#5319E7` | Phase 3: Ecosystem (Months 18-24+) | +| `backend` | `#D93F0B` | Backend (FastAPI, Python) | +| `frontend` | `#FBCA04` | Frontend (OS, UI, JavaScript) | +| `infrastructure` | `#0052CC` | Infrastructure, DevOps, CI/CD | +| `agent` | `#C5DEF5` | Agent-related (Prism, Lucidia, Operator) | +| `security` | `#B60205` | Security issue or enhancement | +| `performance` | `#D4C5F9` | Performance improvement | +| `breaking-change` | `#D93F0B` | Breaking change (major version bump) | + +**Create via GitHub UI**: Settings → Labels → New label + +--- + +## Recommended Workflow Additions + +### 1. PR Labeler + +**File**: `.github/workflows/pr-labeler.yml` + +```yaml +name: PR Labeler +on: + pull_request: + types: [opened, synchronize] + +permissions: + contents: read + pull-requests: write + +jobs: + label: + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@v4 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} +``` + +**Config**: `.github/labeler.yml` + +```yaml +backend: + - backend/**/* + +frontend: + - blackroad-os/**/* + - backend/static/**/* + +infrastructure: + - .github/**/* + - scripts/**/* + - ops/**/* + - infra/**/* + - railway.* + - docker-compose.yml + +documentation: + - docs/**/* + - '**/*.md' + +agent: + - agents/**/* + - blackroad-universe/prompts/**/* +``` + +### 2. Dependabot + +**File**: `.github/dependabot.yml` + +```yaml +version: 2 +updates: + # Backend Python dependencies + - package-ecosystem: "pip" + directory: "/backend" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "backend" + + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + labels: + - "dependencies" + - "infrastructure" + + # Docker + - package-ecosystem: "docker" + directory: "/backend" + schedule: + interval: "weekly" + labels: + - "dependencies" + - "infrastructure" +``` + +### 3. CodeQL Security Scanning + +**File**: `.github/workflows/codeql.yml` + +```yaml +name: CodeQL Security Scan +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '0 6 * * 1' # Monday 6am + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + security-events: write + contents: read + + strategy: + matrix: + language: ['python', 'javascript'] + + steps: + - uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: ${{ matrix.language }} + + - name: Autobuild + uses: github/codeql-action/autobuild@v2 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 +``` + +### 4. Release Automation + +**File**: `.github/workflows/release.yml` + +```yaml +name: Create Release +on: + push: + tags: + - 'v*.*.*' + +jobs: + release: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Generate Changelog + id: changelog + run: | + CHANGELOG=$(git log --pretty=format:"- %s (%h)" $(git describe --tags --abbrev=0 HEAD^)..HEAD) + echo "changelog<> $GITHUB_OUTPUT + echo "$CHANGELOG" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + + - name: Create Release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref_name }} + release_name: Release ${{ github.ref_name }} + body: | + ## Changes in this Release + ${{ steps.changelog.outputs.changelog }} + draft: false + prerelease: false +``` + +--- + +## Best Practices + +### Commit Messages + +**Format**: Conventional Commits + +``` +(): + + + +