blackroad-os/blackroad-operating-system
9
0
Fork 0
mirror of https://github.com/blackboxprogramming/BlackRoad-Operating-System.git synced 2026-03-17 06:57:17 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
387ea8f03c5d1ba37d2575d24e010af6ea93d59d
blackroad-operating-system/ORG_STRUCTURE.md
Claude 0529a05942 Add comprehensive BlackRoad ecosystem implementation plans 
This commit adds detailed implementation plans mapping all 23 BlackRoad
repositories to the 7-layer architecture defined in MASTER_ORCHESTRATION_PLAN.md.

New Documentation:
- ORG_STRUCTURE.md: Complete repo architecture & responsibility map
- IMPLEMENTATION.md: Detailed plan for BlackRoad-Operating-System monolith
- CLOUDFLARE_DNS_BLUEPRINT.md: DNS configuration with repo ownership map

Implementation Plans (in implementation-plans/):
- IMPLEMENTATION_blackroad-api.md: Standalone API gateway (Phase 2)
- IMPLEMENTATION_blackroad-operator.md: Agent orchestration & workflows (Phase 2)
- IMPLEMENTATION_blackroad-prism-console.md: Admin dashboard (Phase 2)
- IMPLEMENTATION_blackroad-io.md: Corporate marketing site (Phase 1)
- IMPLEMENTATION_lucidia.md: Multi-model AI orchestration (Phase 1-2)
- IMPLEMENTATION_blackroad.md: Investigation template for unknown repo

Key Decisions:
- Monolith strategy for Phase 1 (months 0-12)
- Strategic split to microservices in Phase 2 (months 12-18)
- 4 core active repos in Phase 1, expand to 10+ in Phase 2-3
- Cloudflare DNS for all domains with clear repo ownership

Each implementation plan includes:
- Purpose & final role in architecture
- Required GitHub Actions workflows
- Secrets & environment variables
- Cloudflare DNS configuration
- Migration notes from monolith
- Phase-specific milestones
- Success criteria

Ready for Phase 1 execution starting with Week 1 infrastructure tasks.
2025-11-18 02:29:57 +00:00

580 lines
25 KiB
Markdown
Raw Blame History

# 🏢 BLACKROAD GITHUB ORGANIZATION STRUCTURE
## Repository Architecture & Responsibility Map
**Version:** 1.0
**Date:** 2025-11-18
**Author:** Claude (Sonnet 4.5) - BlackRoad Implementation Planning
**Organizations:** `blackboxprogramming` & `BlackRoad-AI`
---
## EXECUTIVE SUMMARY
This document maps **23 BlackRoad repositories** across 2 GitHub organizations to the 7-layer BlackRoad OS architecture defined in `MASTER_ORCHESTRATION_PLAN.md`.
**Key Findings**:
- **1 monolith** currently holds the canonical OS (BlackRoad-Operating-System)
- **6 satellite repos** for specific layers (API, operator, console, frontend sites)
- **8 experimental repos** for advanced features (Lucidia, quantum, AI labs)
- **8 utility/legacy repos** (starters, templates, personal projects)
**Recommended Strategy**: **Consolidate Phase 1** around 4 core repos, archive or migrate the rest.
---
## PART 1: REPOSITORY INVENTORY
### Core Operational Repos (Active in Phase 1)
| Repo | Owner | Purpose | Status | Lines of Code | Last Updated |
|------|-------|---------|--------|---------------|--------------|
| **BlackRoad-Operating-System** | blackboxprogramming | Monolith: OS core, backend API, agents, SDKs, docs | **CANONICAL** | ~50K+ | Active |
| **blackroad-api** | blackboxprogramming | Standalone API gateway (future split from monolith) | Planned | TBD | Stub |
| **blackroad-operator** | blackboxprogramming | Workflow orchestration & scheduled agents | Planned | TBD | Stub |
| **blackroad-prism-console** | blackboxprogramming | Admin UI for Prism job queue & observability | Planned | TBD | Stub |
| **blackroad.io** | blackboxprogramming | Corporate marketing site (blackroad.systems) | Planned | TBD | Stub |
| **BlackRoad.io** | BlackRoad-AI | Alternate corporate site (may be duplicate) | Unknown | TBD | Unknown |
### AI & Intelligence Repos
| Repo | Owner | Purpose | Status | Integration |
|------|-------|---------|--------|-------------|
| **lucidia** | blackboxprogramming | Multi-model AI orchestration layer | Development | Phase 2 |
| **lucidia-lab** | blackboxprogramming | Experimental AI research & testing | Development | Phase 2 |
| **native-ai-quantum-energy** | blackboxprogramming | Quantum computing + AI research | Research | Phase 3 |
| **quantum-math-lab** | blackboxprogramming | Mathematical foundations for quantum OS | Research | Phase 3 |
| **codex-agent-runner** | blackboxprogramming | Agent execution runtime (may merge with operator) | Development | Phase 2 |
| **codex-infinity** | blackboxprogramming | Advanced coding agent system | Development | Phase 2 |
### Utility & Experimental Repos
| Repo | Owner | Purpose | Status | Recommendation |
|------|-------|---------|--------|----------------|
| **blackroad** | blackboxprogramming | Possible legacy or alternative frontend | Unknown | Investigate → Archive or Merge |
| **BlackStream** | blackboxprogramming | Video streaming platform (RoadStream) | Development | Merge into monolith |
| **universal-computer** | blackboxprogramming | Theoretical computing model | Research | Archive (reference only) |
| **remember** | blackboxprogramming | Memory/logging framework | Development | May integrate with Vault |
### Planning & Documentation Repos
| Repo | Owner | Purpose | Status | Recommendation |
|------|-------|---------|--------|----------------|
| **blackroad-plans** | BlackRoad-AI | Strategic planning documents | Active | Keep separate |
### Starter Templates & Examples
| Repo | Owner | Purpose | Status | Recommendation |
|------|-------|---------|--------|----------------|
| **next-video-starter** | blackboxprogramming | Next.js video app template | Template | Archive or move to examples/ |
| **nextjs-ai-chatbot** | blackboxprogramming | Next.js + AI chatbot starter | Template | Archive or integrate features |
### Personal/Meta Repos
| Repo | Owner | Purpose | Status | Recommendation |
|------|-------|---------|--------|----------------|
| **my-repository** | blackboxprogramming | Personal experiments | Unknown | Archive |
| **blackboxprogramming** | blackboxprogramming | Profile README or meta repo | Meta | Keep |
| **new_world** | blackboxprogramming | Possible game or narrative project | Unknown | Investigate → Archive or merge with MetaCity |
---
## PART 2: 7-LAYER ARCHITECTURE MAPPING
### Layer 1: DNS & CDN
**Responsibility**: Domain management, SSL, DDoS protection
| Repo | Role | Implementation |
|------|------|----------------|
| **BlackRoad-Operating-System** | Cloudflare DNS config scripts | `scripts/cloudflare/sync_dns.py` (planned) |
| **blackroad.io** | DNS CNAME targets | `CNAME @ → blackroad-os-production.up.railway.app` |
**Domains Served**:
- `blackroad.systems` → Corporate site
- `os.blackroad.systems` → OS interface
- `api.blackroad.systems` → API gateway
- `prism.blackroad.systems` → Prism Console
- `lucidia.earth` → Narrative experiences (Phase 2)
**Config Files**:
- `ops/domains.yaml` (in monolith)
- Cloudflare dashboard (manual for Phase 1)
---
### Layer 2: Compute & Infrastructure
**Responsibility**: Hosting, containers, orchestration
| Repo | Role | Deployment Target | Config |
|------|------|-------------------|--------|
| **BlackRoad-Operating-System** | Backend API + static UI | Railway | `railway.toml`, `Dockerfile` |
| **blackroad-operator** | Worker processes | Railway (future) | Docker |
| **blackroad-prism-console** | Admin UI | Railway or Vercel | Docker or static |
| **blackroad.io** | Marketing site | Vercel or GitHub Pages | Static build |
**Infrastructure Providers**:
- **Railway**: Backend API, PostgreSQL, Redis (current)
- **DigitalOcean**: RoadChain nodes (Phase 2)
- **Cloudflare Workers**: Edge functions (Phase 2)
- **GitHub Pages**: Documentation sites
---
### Layer 3: Data & State
**Responsibility**: Databases, caching, blockchain, compliance logs
| Repo | Component | Storage | Technology |
|------|-----------|---------|------------|
| **BlackRoad-Operating-System** | User data, app state | PostgreSQL (Railway) | SQLAlchemy 2.0 + asyncpg |
| **BlackRoad-Operating-System** | Session cache | Redis (Railway) | redis-py 5.0 |
| **BlackRoad-Operating-System** | RoadChain ledger | In-memory (Phase 1) → PostgreSQL | Custom blockchain |
| **BlackRoad-Operating-System** | Vault compliance | `compliance_event` table | Immutable audit log |
**Database Schema Owner**: **BlackRoad-Operating-System/backend/app/models/**
**Migration Strategy**:
- Phase 1: Monolith owns all schemas
- Phase 2: Split into service-specific DBs (Prism DB, Lucidia DB, etc.)
---
### Layer 4: Orchestration & Intelligence
**Responsibility**: Agents, jobs, AI orchestration, workflows
| Repo | Component | Purpose | Status |
|------|-----------|---------|--------|
| **BlackRoad-Operating-System** | 200+ agents | Agent library | ✅ Complete (base framework) |
| **lucidia** | Multi-model AI orchestration | Route requests to Claude, GPT, Llama | 🔨 Development |
| **lucidia-lab** | AI experiments | Test new models, prompts | 🔬 Research |
| **blackroad-operator** | Workflow scheduler | Cron-like agent execution | 📋 Planned |
| **blackroad-prism-console** | Job queue UI | Visualize Prism jobs | 📋 Planned |
| **codex-agent-runner** | Agent execution runtime | Run agents in isolated envs | 🔨 Development |
| **codex-infinity** | Advanced coding agents | Generate entire codebases | 🔬 Research |
**API Endpoints** (in BlackRoad-Operating-System):
- `GET /api/agents/library` → List 200+ agents
- `POST /api/agents/{agent_id}/execute` → Run agent
- `GET /api/jobs` → Prism job queue
- `WebSocket /api/jobs/{job_id}/stream` → Real-time updates
---
### Layer 5: API Gateway & Routing
**Responsibility**: REST API, WebSocket, authentication, routing
| Repo | Role | Technology | Endpoints |
|------|------|------------|-----------|
| **BlackRoad-Operating-System** | Canonical API gateway | FastAPI 0.104.1 | 33 routers, 100+ endpoints |
| **blackroad-api** | Future: Standalone API | FastAPI (split from monolith) | Phase 2 migration |
**Current Routers** (in monolith):
```
/api/auth/* → Authentication (JWT)
/api/email/* → RoadMail
/api/social/* → BlackRoad Social
/api/video/* → BlackStream
/api/blockchain/* → RoadChain
/api/miner/* → Mining
/api/agents/* → Agent orchestration (planned)
/api/prism/* → Job queue (planned)
... 25 more routers
```
**Host-Based Routing** (Phase 2):
- `blackroadai.com/*` → Prism theme
- `lucidia.earth/*` → Narrative theme
- `api.blackroad.systems/*` → Developer API
---
### Layer 6: Application Layer (Pocket OS)
**Responsibility**: Windows 95 UI, native apps, real-time sync
| Repo | Component | Technology | Deployment |
|------|-----------|------------|------------|
| **BlackRoad-Operating-System** | Canonical OS UI | Vanilla JS, HTML, CSS | `backend/static/index.html` |
| **blackroad-prism-console** | Admin console | React or Vanilla JS | Separate app |
| **BlackStream** | Video streaming app | Next.js (potential) | May merge into monolith |
| **blackroad** | Possible alternate UI | Unknown | **Investigate → Archive or merge** |
**Native Apps** (embedded in OS):
- RoadMail, BlackRoad Social, BlackStream, RoadChain Explorer
- RoadCoin Miner, Wallet, RoadView Browser, Terminal, File Explorer
- GitHub Manager, Raspberry Pi Manager
- RoadCity, RoadCraft, Road Life (games)
**Duplication Issue**:
- `backend/static/` → **CANONICAL**
- `blackroad-os/` → **LEGACY** (superseded, mark as deprecated)
---
### Layer 7: User Experience (Multi-Domain)
**Responsibility**: Marketing sites, developer docs, narrative experiences
| Repo | Domain | Purpose | Technology | Status |
|------|--------|---------|------------|--------|
| **blackroad.io** | blackroad.systems | Corporate site | HTML/CSS or Next.js | 📋 Planned |
| **BlackRoad.io** | TBD (may be duplicate) | Unknown | Unknown | ❓ Investigate |
| **BlackRoad-Operating-System** | os.blackroad.systems | OS interface | FastAPI + static | ✅ Live |
| **blackroad-plans** | Internal only | Planning docs | Markdown | ✅ Active |
| **BlackRoad-Operating-System** | blackroad.network | Developer docs | MkDocs or Docusaurus | 📋 Planned |
| **lucidia** | lucidia.earth | Narrative site | Next.js (Phase 2) | 📋 Planned |
**Domain Ownership** (from MASTER_ORCHESTRATION_PLAN.md):
```
blackroad.systems → blackroad.io repo (corporate)
os.blackroad.systems → BlackRoad-Operating-System (OS)
api.blackroad.systems → blackroad-api (future) or monolith (Phase 1)
prism.blackroad.systems → blackroad-prism-console
blackroad.network → BlackRoad-Operating-System/docs/ (developer)
lucidia.earth → lucidia repo (narrative)
aliceqi.com → quantum-math-lab or lucidia-lab (research)
```
---
## PART 3: RECOMMENDED REPOSITORY STRATEGY
### Phase 1 (Months 0-12): Consolidate Around Monolith
**Active Repos** (4 core):
1. **BlackRoad-Operating-System** → Canonical monolith (OS, API, agents, docs)
2. **blackroad.io** → Corporate marketing site
3. **blackroad-plans** → Strategic planning (separate org)
4. **lucidia** → AI layer (development starts mid-Phase 1)
**Archive** (move to `archive/` or mark read-only):
- `blackroad-os/` → Superseded by `backend/static/`
- `next-video-starter` → Template, not core product
- `nextjs-ai-chatbot` → Template, integrate features into monolith if needed
- `my-repository` → Personal, not product
- `universal-computer` → Research reference only
**Investigate** (determine keep/merge/archive):
- `blackroad` → If alternate UI, merge or archive
- `BlackRoad.io` → If duplicate of blackroad.io, archive
- `new_world` → Merge with MetaCity if game-related, else archive
**Keep as Experimental**:
- `lucidia-lab` → Research & testing
- `quantum-math-lab` → Long-term research
- `native-ai-quantum-energy` → Long-term research
- `remember` → May integrate into Vault
---
### Phase 2 (Months 12-18): Strategic Split
**New Active Repos**:
1. **blackroad-api** → Extract API gateway from monolith
2. **blackroad-operator** → Workflow orchestration & scheduler
3. **blackroad-prism-console** → Admin UI for observability
4. **BlackStream** → Standalone video platform
**Monolith Becomes**:
- **BlackRoad-Operating-System** → Core runtime, identity (PS-SHA∞), RoadChain
**Migration Strategy**:
```
Monolith (Phase 1)
├── backend/app/routers/* → blackroad-api/routers/
├── agents/ → blackroad-operator/agents/
├── backend/static/ → Keep in monolith (OS shell)
└── docs/ → blackroad-network (GitHub Pages)
```
---
### Phase 3 (Months 18-24+): Microservices & Ecosystem
**Additional Repos**:
- **blackroad-vault** → Compliance & audit ledger
- **blackroad-cloudway** → Infrastructure as software
- **blackroad-roadchain** → Blockchain network
- **blackroad-metacity** → Gaming platform
**Full Ecosystem** (10 repos):
```
┌─────────────────────────────────────────────────────────────┐
│ USER-FACING │
├─────────────────────────────────────────────────────────────┤
│ blackroad.io → Corporate site │
│ BlackRoad-Operating-System → OS shell (minimal) │
│ blackroad-prism-console → Admin UI │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ BACKEND SERVICES │
├─────────────────────────────────────────────────────────────┤
│ blackroad-api → REST/GraphQL gateway │
│ blackroad-operator → Workflows & scheduler │
│ lucidia → AI orchestration │
│ blackroad-vault → Compliance ledger │
│ blackroad-cloudway → Infrastructure automation │
│ blackroad-roadchain → Blockchain nodes │
│ blackroad-metacity → Gaming backend │
└─────────────────────────────────────────────────────────────┘
```
---
## PART 4: GITHUB ORG RECOMMENDATIONS
### Current State
- **blackboxprogramming** org → 20 repos (mix of active, experimental, personal)
- **BlackRoad-AI** org → 2 repos (blackroad-plans, BlackRoad.io)
### Recommended Structure
**Option A: Consolidate into single `blackroad` org**
- Create new `blackroad` GitHub organization
- Migrate all product repos from `blackboxprogramming` and `BlackRoad-AI`
- Keep `blackboxprogramming` for personal/experimental work
- **Pros**: Clear branding, professional, easier permissions
- **Cons**: Migration effort, URL changes
**Option B: Keep `blackboxprogramming`, clean it up**
- Archive/delete non-product repos
- Rename to `blackroad-os` or `blackroad-ai` (GitHub allows org rename)
- **Pros**: No migration, URLs stay same
- **Cons**: Less professional name
**Option C: Hybrid (Recommended for Phase 1)**
- Keep `blackboxprogramming` as-is for Phase 1 (minimize disruption)
- Create `blackroad` org for Phase 2 (migrate core repos)
- Use topics/tags to distinguish product vs. experimental repos
- **Pros**: Gradual transition, low risk
- **Cons**: Temporary complexity
### GitHub Teams (Future)
Once org structure is solidified:
```
@blackroad/core → Alexa + senior engineers (all repos)
@blackroad/frontend → UI/UX contributors (OS, Prism Console)
@blackroad/backend → API/infrastructure (API, Operator, CloudWay)
@blackroad/ai → AI/ML contributors (Lucidia, agents)
@blackroad/docs → Documentation writers (docs, README)
@blackroad/community → External contributors (all repos, triage role)
```
### CODEOWNERS Consolidation
**Monolith** (`BlackRoad-Operating-System/.github/CODEOWNERS`):
```
# Global owners
* @alexa-amundson @cadillac
# Backend
/backend/app/** @blackroad/backend @alexa-amundson
# Frontend
/backend/static/** @blackroad/frontend @alexa-amundson
# Agents
/agents/** @blackroad/ai @alexa-amundson
# Infrastructure
/.github/workflows/** @blackroad/backend
/scripts/** @blackroad/backend
/ops/** @alexa-amundson
# Docs
/docs/** @blackroad/docs
/README.md @blackroad/docs
```
**Future Repos**: Each repo gets its own CODEOWNERS with `@blackroad/core` as global owner
---
## PART 5: CANONICAL WORKFLOWS
### Required GitHub Actions (All Active Repos)
| Workflow | File | Purpose | Runs On |
|----------|------|---------|---------|
| **CI** | `.github/workflows/ci.yml` | Lint, type-check, test | Push, PR → main |
| **Deploy** | `.github/workflows/deploy.yml` | Deploy to Railway/Vercel | Push → main (after CI passes) |
| **Security** | `.github/workflows/codeql.yml` | CodeQL security scan | Weekly, PR → main |
| **Dependencies** | `.github/dependabot.yml` | Auto-update deps | Daily |
### Repo-Specific Workflows
**BlackRoad-Operating-System** (monolith):
- `backend-tests.yml` → Run pytest
- `railway-deploy.yml` → Deploy to Railway
- `railway-automation.yml` → Env validation
- `domain-health.yml` → Multi-domain health checks
**blackroad.io** (marketing site):
- `build.yml` → Build Next.js/static site
- `deploy-vercel.yml` → Deploy to Vercel
**blackroad-api** (future):
- `api-tests.yml` → API contract tests
- `railway-deploy.yml` → Deploy API service
**lucidia** (AI layer):
- `model-tests.yml` → Test AI model integrations
- `deploy.yml` → Deploy to Railway
---
## PART 6: MIGRATION CHECKLIST
### Immediate Actions (This Week)
- [ ] **Deprecate `blackroad-os/` directory in monolith**
- Add README: "⚠️ LEGACY: This directory is superseded by `backend/static/`. Do not edit."
- Update all docs to reference `backend/static/` only
- Archive or delete after verification
- [ ] **Investigate duplicate repos**
- [ ] Check if `blackroad` repo has different code than `backend/static/`
- [ ] Check if `BlackRoad.io` is duplicate of `blackroad.io` plan
- [ ] Document findings, recommend archive or merge
- [ ] **Tag experimental repos**
- Add GitHub topic tags: `experimental`, `research`, `phase-2`, `phase-3`
- Update repo descriptions to clarify status
### Phase 1 Setup (Weeks 1-4)
- [ ] **Create `blackroad.io` repo**
- Use `next-video-starter` or simple HTML as template
- Implement 5-page MVP (from NEXT_ACTIONS_ALEXA.md)
- Deploy to Vercel or GitHub Pages
- Point `blackroad.systems` DNS
- [ ] **Set up `blackroad-plans` integration**
- Link from monolith README
- Reference in MASTER_ORCHESTRATION_PLAN.md
- Keep as single source of truth for strategy docs
- [ ] **Create ORG_STRUCTURE.md in all active repos**
- Link to this canonical version in monolith
- Each repo gets a "Role in Ecosystem" section
### Phase 2 Preparation (Months 6-12)
- [ ] **Scaffold future repos**
- Create `blackroad-api` stub (copy backend/app/, remove static/)
- Create `blackroad-operator` stub (copy agents/, add scheduler)
- Create `blackroad-prism-console` stub (React app)
- Mark as "UNDER DEVELOPMENT - Phase 2"
- [ ] **Plan migration scripts**
- `scripts/migrate_api.sh` → Extract backend/app/routers/ to blackroad-api
- `scripts/migrate_agents.sh` → Extract agents/ to blackroad-operator
- Document in MIGRATION_GUIDE.md
### Phase 3 (Months 12+)
- [ ] **Create new org (optional)**
- If going with Option A, create `blackroad` org
- Transfer repos from `blackboxprogramming` and `BlackRoad-AI`
- Update all docs, CI/CD with new URLs
- [ ] **Microservices repos**
- `blackroad-vault`, `blackroad-cloudway`, `blackroad-roadchain`, `blackroad-metacity`
- Each with own CI/CD, deployment, docs
---
## PART 7: REPO HEALTH METRICS
### Recommended Tracking (Per Repo)
| Metric | Tool | Frequency |
|--------|------|-----------|
| **Test Coverage** | pytest-cov, CodeCov | Every CI run |
| **Build Status** | GitHub Actions badges | Real-time |
| **Dependencies** | Dependabot alerts | Daily |
| **Security** | CodeQL, Snyk | Weekly |
| **Code Quality** | SonarCloud, CodeClimate | Every PR |
| **Deploy Status** | Railway/Vercel status checks | Every deploy |
### Monolith Health Dashboard
Add to `README.md`:
```markdown
## 📊 Repository Health
| Component | Status | Coverage | Last Deploy |
|-----------|--------|----------|-------------|
| Backend API | ![CI](https://github.com/.../workflows/ci.yml/badge.svg) | 75% | 2025-11-18 |
| Frontend | ![CI](https://github.com/.../workflows/ci.yml/badge.svg) | N/A | 2025-11-18 |
| Agents | ![Tests](https://github.com/.../workflows/backend-tests.yml/badge.svg) | 60% | 2025-11-15 |
| Deployment | ![Railway](https://img.shields.io/badge/railway-deployed-success) | - | 2025-11-18 |
```
---
## PART 8: QUICK REFERENCE
### Repo Ownership Matrix
| Repo | Primary Owner | Secondary Owner | Purpose | Status |
|------|---------------|-----------------|---------|--------|
| BlackRoad-Operating-System | @alexa-amundson | @blackroad/core | Monolith (OS, API, agents) | Active |
| blackroad.io | @alexa-amundson | @blackroad/frontend | Corporate site | Planned |
| blackroad-plans | @alexa-amundson | - | Strategic planning | Active |
| lucidia | @alexa-amundson | @blackroad/ai | AI orchestration | Development |
| blackroad-api | @alexa-amundson | @blackroad/backend | API gateway | Phase 2 |
| blackroad-operator | @alexa-amundson | @blackroad/backend | Workflow orchestration | Phase 2 |
| blackroad-prism-console | @alexa-amundson | @blackroad/frontend | Admin UI | Phase 2 |
### Documentation Hierarchy
```
┌─────────────────────────────────────────────────────────────┐
│ MASTER DOCS (in BlackRoad-Operating-System) │
├─────────────────────────────────────────────────────────────┤
│ MASTER_ORCHESTRATION_PLAN.md → Complete 7-layer blueprint │
│ ORG_STRUCTURE.md (this file) → Repo architecture │
│ NEXT_ACTIONS_ALEXA.md → Execution checklist │
│ BLACKROAD_OS_BIG_KAHUNA_VISION.md → 18-24 month roadmap │
│ CLAUDE.md → AI assistant guide │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ REPO-SPECIFIC DOCS (in each repo) │
├─────────────────────────────────────────────────────────────┤
│ IMPLEMENTATION.md → This repo's plan │
│ README.md → Overview, setup │
│ CONTRIBUTING.md → How to contribute │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ STRATEGIC DOCS (in blackroad-plans) │
├─────────────────────────────────────────────────────────────┤
│ [Plans, roadmaps, strategy documents] │
└─────────────────────────────────────────────────────────────┘
```
---
## CONCLUSION
**Current State**: 23 repos across 2 orgs with unclear boundaries and some duplication
**Target State** (Phase 1): 4 core active repos with clear roles, 15 archived/experimental
**Execution Strategy**:
1. **Week 1**: Deprecate duplicates, tag experimental repos
2. **Weeks 2-4**: Create blackroad.io, set up docs
3. **Months 3-6**: Start lucidia development
4. **Months 6-12**: Plan Phase 2 splits (API, operator, console)
5. **Months 12+**: Microservices architecture
**Next Steps**: Create `IMPLEMENTATION.md` in each core repo with detailed plans.
---
*This document is the single source of truth for BlackRoad repository organization. Update as architecture evolves.*
**Last Updated**: 2025-11-18
**Next Review**: 2025-12-18 (monthly)
Reference in New Issue View Git Blame Copy Permalink