Skip to main content

Internal Documentation Architecture

Purpose​

Defines the architecture and deployment strategy for Symphony Core's internal documentation platform hosted at team.symphonycore.com.

Scope​

Covers the complete technical implementation including authentication, deployment pipeline, and content management for internal team documentation.

System Overview​

Current Production Setup (As of December 2025)​

Repository: symphonycore-org/internal-docs (https://github.com/symphonycore-org/internal-docs) Cloudflare Pages: symphonycore-docs project Cloudflare Access: Edge authentication with One-time PIN Production URL: https://team.symphonycore.com Preview URL: https://symphonycore-docs.pages.dev

Architecture Diagram​

User Request
     │
     ▼
┌─────────────────────────────────┐
│      Cloudflare Access          │
│   (Edge Authentication)         │
│   - One-time PIN via email      │
│   - @symphonycore.com policy    │
│   - 1 month session duration    │
└──────────────┬──────────────────┘
               │ Authenticated
               ▼
┌─────────────────────────────────┐
│      Cloudflare Pages           │
│   (Static Site Hosting)         │
│   - Global CDN                  │
│   - Auto-deploy from GitHub     │
└──────────────┬──────────────────┘
               │
               ▼
┌─────────────────────────────────┐
│      Docusaurus Site            │
│   - Static HTML/JS/CSS          │
│   - Local search                │
│   - MDX content                 │
└─────────────────────────────────┘

Component Architecture​

Frontend Layer​

Technology Stack:

  • Framework: Docusaurus 3.8.1
  • Runtime: React 18.x
  • Language: JavaScript/TypeScript
  • Styling: CSS Modules with custom themes
  • Search: @easyops-cn/docusaurus-search-local

Key Features:

  • Markdown-powered content management (MDX support)
  • Local search functionality with highlighting
  • Mobile-responsive design
  • Dark/light mode support
  • Static site generation for optimal performance

Authentication Layer​

Cloudflare Access:

  • Method: One-time PIN (email-based OTP)
  • Policy: Allow emails ending in @symphonycore.com
  • Session Duration: 1 month
  • Location: Edge-level (before content is served)

How It Works:

  1. User navigates to team.symphonycore.com
  2. Cloudflare Access intercepts request
  3. User enters email address
  4. User receives one-time PIN via email
  5. User enters PIN to authenticate
  6. Session cookie set (1 month duration)
  7. User accesses documentation

Benefits:

  • No client-side auth code needed
  • Faster page loads (no auth SDK)
  • Supports external users via email OTP
  • Authentication happens before content loads
  • Reduced bundle size

Deployment Pipeline​

Cloudflare Pages Integration:

  • Automatic builds on Git push to master
  • Edge deployment for global performance
  • Custom domain configuration
  • SSL/TLS termination

Build Process:

  1. Source code changes pushed to GitHub
  2. Cloudflare Pages webhook triggered
  3. Node.js build environment provisioned
  4. Dependencies installed via npm
  5. Docusaurus build executed
  6. Static assets deployed to edge network

Repository Structure​

internal-docs/
├── docs/                                  # Documentation content (MDX)
│   ├── index.md                          # Homepage
│   ├── architecture/
│   │   └── internal-docs/                # Platform documentation
│   │       ├── system-architecture.md
│   │       ├── publishing-guide.md
│   │       ├── quick-reference.md
│   │       ├── troubleshooting.md
│   │       └── cms-setup.md
│   ├── maintenance/                      # Operational docs
│   │   ├── security-cleanup-required.md
│   │   ├── cms-test-plan.md
│   │   ├── environment-setup.md
│   │   └── migration-history-2025-09.md
│   └── project-management/
│       └── implementation-plan.md
├── src/
│   ├── css/
│   │   └── custom.css                    # Custom styling
│   └── img/
│       └── logo.svg                      # Application logo
├── static/
│   ├── img/
│   │   └── logo.svg                      # Bundled logo
│   ├── admin/
│   │   └── config.yml                    # Sveltia CMS configuration
│   └── favicon.ico
├── scripts/
│   └── upload-media.js                   # Cloudflare R2 media upload utility
├── docusaurus.config.js                  # Main Docusaurus configuration
├── sidebars.config.js                    # Sidebar navigation structure
├── package.json                          # Dependencies and scripts
└── README.md                             # Project documentation

Configuration Specifications​

Docusaurus Configuration​

Core Settings:

Plugin Configuration:

  • @docusaurus/preset-classic
  • @easyops-cn/docusaurus-search-local

Cloudflare Access Configuration​

Application Settings:

  • Name: Internal Docs
  • Domain: team.symphonycore.com
  • Session Duration: 1 month

Access Policy:

  • Name: Symphony Core Team
  • Action: Allow
  • Selector: Emails ending in @symphonycore.com

Identity Provider:

  • One-time PIN (email OTP)

Management:

Cloudflare Pages Settings​

Project Details:

  • Project Name: symphonycore-docs
  • Repository: symphonycore-org/internal-docs
  • Branch: master
  • Framework: Docusaurus

Build Configuration:

  • Build command: npm run build
  • Output directory: build
  • Node.js version: 18.x or higher

Custom Domain:

  • Primary domain: team.symphonycore.com
  • Preview domain: symphonycore-docs.pages.dev
  • HTTPS enforcement: Enabled

Security Implementation​

Access Control​

Cloudflare Access Policy:

  • Only @symphonycore.com emails allowed by default
  • External users can be added individually
  • Session duration: 1 month
  • Edge-level enforcement (before content loads)

Adding External Users:

  1. Go to Cloudflare Zero Trust Dashboard
  2. Access controls → Applications → Internal Docs
  3. Edit policy to add specific email addresses

Data Protection​

Content Security:

  • No external script injection
  • Sanitized markdown rendering
  • XSS protection enabled

Infrastructure Security:

  • TLS 1.3 encryption
  • HSTS headers enabled
  • Cloudflare DDoS protection

Performance Optimization​

Build Optimization​

Static Generation:

  • Pre-rendered HTML pages
  • Optimized asset bundling
  • Tree-shaking for unused code

Delivery Optimization​

CDN Configuration:

  • Global edge locations
  • Automatic caching rules
  • Compression enabled (Brotli/Gzip)
  • HTTP/2 and HTTP/3 support

Maintenance Procedures​

Content Updates​

Process:

  1. Edit content via CMS (team.symphonycore.com/admin) or Git
  2. Changes auto-deploy on merge to master
  3. Verify deployment in Cloudflare Pages dashboard

Access Management​

Adding @symphonycore.com Users:

  • No action needed - automatic access

Adding External Users:

  1. Cloudflare Zero Trust → Access controls → Applications
  2. Edit "Internal Docs" application
  3. Add Include rule with specific email

Security Updates​

Regular Tasks:

  • Dependency updates (monthly)
  • Access policy review (quarterly)
  • Domain access audit (quarterly)

Disaster Recovery​

Backup Strategy​

Data Backup:

  • GitHub repository (primary)
  • Cloudflare automatic backups
  • Local development copies

Recovery Procedures:

  • Repository restoration from GitHub
  • Cloudflare Pages redeployment
  • DNS failover configuration