Documentation Visibility Guide

Last Updated: 2025-11-11
Purpose: Define which documentation is public vs internal-only

📊 Documentation Categories

🌍 Public Documentation (External Developers & Users)

Location: All pages except /private/* and /architecture/internal-*

Audience:

• External developers
• API consumers
• League owners
• Sportsbook partners
• Public users
• Open source contributors

Content Guidelines:

• No sensitive credentials
• No internal infrastructure details
• No proprietary business logic
• No employee information
• No internal tooling details
• No cost/budget information

Examples:

• /architecture/* (most pages) ✅
• /api/reference ✅
• /getting-started ✅
• /guides ✅
• /schemas ✅

🔒 Internal Documentation (Team Only)

Location: /private/* and /architecture/internal-*

Audience:

• Internal team members
• Developers with access
• DevOps engineers
• Technical leadership

Content Guidelines:

• Can include sensitive information
• Infrastructure details
• Credentials management
• Internal processes
• Cost tracking
• Team structure

Examples:

• /private/company/* 🔒
• /private/intelligence/* 🔒
• /private/integrations/* 🔒
• /architecture/internal-infrastructure 🔒
• /architecture/internal-deployment 🔒
• /architecture/internal-monitoring 🔒

🎯 Page Classification Matrix

🔐 Access Control Strategy

Development Environment

Local: All pages visible (for development)

Production Deployment

Options for Internal Docs:

1. Separate Deployment (Recommended)

   • Deploy to: internal-docs.altsportsleagues.ai
   • Add authentication (Vercel password protection)
   • Keep separate from public docs

2. Build-Time Filtering

   • Filter out /private/* during public build
   • Include all in internal build
   • Deploy both separately

3. Runtime Authentication

   • Deploy all pages
   • Use middleware to check auth
   • Redirect unauthorized users

🛠️ Implementation Approach

Recommended: Separate Deployments

Public Docs Build:

# Build without private pages
cd clients/docs-site
EXCLUDE_PRIVATE=true npm run build
 
# Or use custom build script
npm run build:public

Internal Docs Build:

# Build with all pages
cd clients/docs-site
npm run build
 
# Deploy to separate URL
vercel --prod --alias internal-docs

Build Script Configuration

package.json:

{
  "scripts": {
    "build:public": "DOCS_VISIBILITY=public next build",
    "build:internal": "DOCS_VISIBILITY=internal next build",
    "deploy:public": "npm run build:public && vercel --prod",
    "deploy:internal": "npm run build:internal && vercel --prod --alias internal-docs"
  }
}

next.config.js (filter private pages):

const nextConfig = {
  // ... other config
  
  async redirects() {
    // If building public docs, redirect private pages to 404
    if (process.env.DOCS_VISIBILITY === 'public') {
      return [
        {
          source: '/private/:path*',
          destination: '/404',
          permanent: false
        },
        {
          source: '/architecture/internal-:path*',
          destination: '/404',
          permanent: false
        }
      ];
    }
    return [];
  }
};

📋 Content Review Checklist

Before Publishing Public Docs

Review each page for:

• No API keys or passwords
• No internal email addresses (use generic ones)
• No actual database connection strings
• No service account details
• No employee names (unless public-facing)
• No internal cost data (use estimates)
• No proprietary algorithms
• No internal project IDs (use placeholders)
• No internal Slack/communication channels
• No vulnerability details

Sanitization Examples

❌ Internal (Don't Publish):

# Actual connection string
NEO4J_URI = "neo4j+s://abc123.databases.neo4j.io"
NEO4J_PASSWORD = "actual-password-here"

✅ Public (Safe to Publish):

# Example connection string (placeholder)
NEO4J_URI = "neo4j+s://YOUR_INSTANCE.databases.neo4j.io"
NEO4J_PASSWORD = "<stored-in-secret-manager>"

❌ Internal (Don't Publish):

# Actual GCP project
gcloud config set project altsportsdata-102243

✅ Public (Safe to Publish):

# Your GCP project
gcloud config set project YOUR_PROJECT_ID

🎯 Migration Path

Current State

• All docs in single site
• No visibility controls
• Everything potentially public

Target State (Phased Approach)

Phase 1: Mark Internal Pages ✅ DONE

• Added callouts to internal pages
• Updated _meta.ts with internal section
• Created visibility guide (this document)

Phase 2: Separate Builds (Next)

• Create build:public script
• Filter private/* during public build
• Test both builds locally

Phase 3: Dual Deployment (Future)

• Deploy public to docs.altsportsleagues.ai
• Deploy internal to internal-docs.altsportsleagues.ai
• Add Vercel password protection to internal

Phase 4: Authentication (Future)

• Add proper auth (Firebase or Clerk)
• Role-based access control
• Audit logging for sensitive pages

📊 Visibility by Section

Total Documentation:

• Public pages: ~180 pages (90%)
• Internal pages: ~20 pages (10%)