Skip to main content

EGI-SOP Documentation Site Design

Date: 2026-03-25 Status: Approved Project: Internal SOP and Standards Library for EGI

Executive Summary

EGI-SOP is an internal documentation site built with Docusaurus that serves as the central source of truth for company operations, engineering standards, SKU standards, pricing references, and operational workflows. The project consolidates documentation from multiple sources (egi-engine, egi-ci:cd, scattered docs) into a single, well-organized, maintainable documentation system.

Key Goals:

  • Consolidate scattered documentation into one authoritative source
  • Update all content to reflect new tooling stack (Slack, ERPNext, PostHog, Cloudflare, Uptime Kuma, CrowdSec, Stripe, etc.)
  • Create strong information architecture for long-term growth
  • Enable easy contribution by technical team and AI tools
  • Deploy via GitOps workflow to Vercel

Approach: Comprehensive migration - build complete structure and migrate all existing content in one pass, updating tool references throughout.

Project Context

Existing Documentation Sources

egi-engine (~/Developer/egi-engine):

  • SKU standards and tooling (standards/sku/)
  • Operational runbooks (docs/runbooks/)
  • Platform usage guides and adapter documentation

egi-ci:cd (~/Developer/egi-ci:cd):

  • Golden path CI/CD documentation
  • Architecture Decision Records (ADRs)
  • Repository conventions and standards
  • How-to guides for project setup

Tool Consolidation

EGI is consolidating from scattered internal tools to a focused stack:

Current Tooling Stack:

  • Slack - Internal communication
  • ERPNext - ERP system (replacing scattered Google Drive docs)
  • PostHog - Analytics and instrumentation
  • Cloudflare - DNS, security, CDN
  • Uptime Kuma - Uptime monitoring and alerting
  • CrowdSec - Intrusion detection for Linux cloud instances
  • Docusaurus - Documentation system (this project)
  • Vercel - Hosting platform
  • Penpot - Design tool
  • Stripe - Payment processing

All migrated documentation will be updated to reference this consolidated stack.

Architecture

Project Structure

egi-sop/
├── docs/ # Main documentation
│ ├── company-operations/
│ ├── engineering-standards/
│ ├── product-operations/
│ ├── client-delivery/
│ ├── sku-standards/
│ ├── pricing-standards/
│ ├── tooling-stack/
│ ├── auth-access/
│ ├── monitoring-incident/
│ ├── onboarding-offboarding/
│ ├── migration-archival/
│ └── reference-library/
├── blog/ # Changelog/announcements
├── static/
│ ├── img/ # Logos, images
│ └── assets/ # Other static files
├── src/
│ ├── components/ # Custom React components
│ ├── css/ # Custom styles (branding)
│ └── pages/ # Custom pages (homepage, etc.)
├── docusaurus.config.js # Main configuration
├── sidebars.js # Sidebar navigation
├── package.json
└── README.md # Maintenance instructions

URL Structure

  • Documentation: /docs/[section]/[page]
    • Example: /docs/engineering-standards/repo-conventions
  • Blog: /blog/[slug]
    • Example: /blog/2026/03/25/new-crowdsec-standard
  • Custom Pages: /[page]
    • Example: / (homepage)

Sidebar Structure:

  • 12 main sections (collapsible)
  • Each section has an index page (overview) plus sub-pages
  • Sidebar defined in sidebars.js
  • Automatic breadcrumbs for deep navigation

Search:

  • Docusaurus built-in local search (fast, no external dependencies)
  • Upgradeable to Algolia if needed later

Content Migration Strategy

From egi-engine

1. SKU Standards (standards/sku/docs/sku-standards/)

  • Migrate README.md content as main standards documentation
  • Document platforms.json and system_types.json structure
  • Add references/links to gen_sku.py and sku_audit.py tools (tools remain in egi-engine repo)
  • Update any references to old tooling

2. Operational Runbooks (docs/runbooks/docs/monitoring-incident/runbooks/)

  • Migrate all runbook markdown files
  • Update tool references (add CrowdSec, Uptime Kuma procedures)
  • Cross-reference with monitoring standards
  • Update incident response procedures

3. Platform Documentation (docs/ → Various sections)

  • Platform usage guide → docs/tooling-stack/ or docs/engineering-standards/
  • Adapter docs → docs/engineering-standards/integrations/
  • Control center docs → Appropriate sections based on content

From egi-ci:cd

1. Golden Path Documentation (docs/docs/engineering-standards/)

  • Architecture docs → engineering-standards/architecture.md
  • ADRs → engineering-standards/decisions/
  • How-to guides → engineering-standards/getting-started/
  • Repo structure standards → engineering-standards/repo-conventions.md
  • Provider adapters → engineering-standards/ci-cd/

2. Templates (templates/docs/reference-library/templates/)

  • Migrate existing templates
  • Combine with newly created templates

Tool Reference Updates

Throughout all migrated content, update references to reflect the consolidated tooling stack:

  • Replace old/deprecated tool mentions with current stack
  • Add CrowdSec configuration and intrusion detection procedures
  • Add PostHog instrumentation expectations and examples
  • Add Uptime Kuma monitoring setup procedures
  • Add Stripe payment integration patterns and standards
  • Reference ERPNext for relevant business workflows
  • Note Slack as primary communication channel with conventions
  • Update deployment references to reflect current platforms

Branding & Theme

Color Palette

Based on https://egintegrations.com:

  • Primary: Cream/beige (#F5F1E8 or similar)
    • Used for cards, highlights, accents
  • Secondary: Dark navy/charcoal (#1A1D23 or similar)
    • Used for backgrounds, headers, dark mode
  • Accent: Blue (#0096D6 or similar)
    • Used for links, CTAs, interactive elements
  • Logo Colors: Orange/coral from EGI mark

Typography

  • Headings: Bold, modern sans-serif
    • Candidates: Inter, Space Grotesk, DM Sans, or similar Google Font
  • Body: Clean sans-serif for optimal readability
  • Code: Standard monospace fonts

Theme Customization

Dark Mode:

  • Dark navy backgrounds (#1A1D23)
  • Cream text and accents (#F5F1E8)
  • Blue links and interactive elements

Light Mode:

  • Cream backgrounds (#F5F1E8)
  • Dark text (#1A1D23)
  • Blue accents for links

Visual Style:

  • Clean, professional, technical but approachable
  • Card-based layouts where appropriate
  • Clear visual hierarchy with bold headings
  • Ample whitespace for readability
  • Rounded corners on buttons and interactive elements
  • Code-friendly formatting for technical content

Custom Elements:

  • EGI logo in navbar
  • Custom CSS for cards, buttons, callouts matching brand
  • Consistent component styling across site

Documentation Sections

1. Company Operations (docs/company-operations/)

Overview: Internal company operation standards and expectations.

Pages:

  • index.md - Overview of company operations philosophy
  • communication-standards.md - Internal communication expectations
  • slack-conventions.md - Slack usage, channel naming, threading rules, notification etiquette
  • ownership-model.md - Ownership expectations and accountability framework
  • documentation-standards.md - Documentation requirements and best practices
  • workflow-rules.md - Internal workflow standards and collaboration patterns

2. Engineering Standards (docs/engineering-standards/)

Overview: Engineering practices, standards, and the golden path for development.

Pages:

  • index.md - Overview of engineering philosophy and standards
  • repo-conventions.md - Repository naming, structure, README requirements (from egi-ci:cd)
  • development-workflow.md - Development standards, branching, commit messages
  • approval-gates.md - Code review and approval requirements
  • release-procedures.md - How to release software safely
  • rollback-procedures.md - How to safely rollback releases
  • documentation-requirements.md - Per-repo documentation standards
  • ai-assisted-development.md - Standards and best practices for working with AI tools
  • architecture.md - Architecture principles and patterns (from egi-ci:cd)
  • decisions/ - Architecture Decision Records (ADRs from egi-ci:cd)
  • ci-cd/ - Golden path CI/CD documentation (from egi-ci:cd)
  • integrations/ - Provider adapters and integration patterns (from egi-engine)

3. Product Operations (docs/product-operations/)

Overview: Product lifecycle management and operational standards.

Pages:

  • index.md - Overview of product operations
  • product-lifecycle.md - Product stages from concept to sunset
  • launch-checklist.md - Pre-launch requirements and validation
  • release-checklist.md - Release process and verification
  • analytics-instrumentation.md - PostHog setup and instrumentation standards
  • feature-flags.md - Feature flag usage, conventions, and lifecycle
  • support-ownership.md - Support ownership model and escalation

4. Client Delivery (docs/client-delivery/)

Overview: Standards for delivering projects to clients.

Pages:

  • index.md - Overview of client delivery philosophy
  • onboarding-workflow.md - How to onboard new clients
  • documentation-expectations.md - Client-facing documentation standards
  • handoff-procedures.md - Transitioning projects to clients
  • deployment-standards.md - Deployment expectations and patterns for client projects
  • ownership-model.md - Post-delivery ownership and responsibility model
  • support-model.md - Support SLAs, procedures, and escalation paths

5. SKU Standards (docs/sku-standards/)

Overview: SKU naming, versioning, and management standards.

Content Source: Migrated from egi-engine standards/sku/

Pages:

  • index.md - SKU philosophy and overview (from README.md)
  • naming-conventions.md - SKU naming and versioning rules
  • platform-identifiers.md - Platform codes and definitions (from platforms.json)
  • system-types.md - System type definitions and usage (from system_types.json)
  • release-conventions.md - How SKUs evolve with product releases
  • examples.md - Real-world SKU examples with explanations
  • tooling.md - Links to gen_sku.py and sku_audit.py in egi-engine repo
  • update-process.md - How to propose and implement SKU standard updates

6. Pricing Standards (docs/pricing-standards/)

Overview: Pricing methodology, estimation, and packaging standards.

Pages:

  • index.md - Overview and pricing philosophy
  • pricing-methodology.md - How pricing is determined and calculated
  • estimation-standards.md - Quoting and estimation best practices
  • packaging-rules.md - How to package services and products
  • stripe-integration.md - Stripe payment integration patterns and standards
  • calculator-reference.md - Pricing calculator usage and maintenance
  • pricing-tiers.md - Standard pricing tiers and their corresponding SKUs

7. Tooling Stack (docs/tooling-stack/)

Overview: Documentation for all tools in the EGI stack.

Pages:

  • index.md - Complete tooling overview and philosophy
  • slack.md - Purpose, usage patterns, channel conventions, integrations
  • erpnext.md - ERP usage, workflows, and best practices
  • posthog.md - Analytics setup, event tracking, and analysis
  • cloudflare.md - DNS management, security features, CDN usage
  • uptime-kuma.md - Monitoring setup, alerting configuration, procedures
  • crowdsec.md - Intrusion detection setup, response procedures, maintenance
  • docusaurus.md - This documentation system, contribution workflow
  • vercel.md - Deployment platform, configuration, best practices
  • penpot.md - Design tool usage, file organization, collaboration
  • stripe.md - Payment processing, integration patterns, testing

8. Auth & Access (docs/auth-access/)

Overview: Authentication patterns and access control across systems.

Pages:

  • index.md - Overview of authentication and access management
  • auth-patterns.md - Current authentication implementations across systems
  • access-expectations.md - Internal access policies and principles
  • documenting-auth.md - How to document authentication per system
  • account-provisioning.md - Account setup and provisioning procedures
  • future-planning.md - Authentication consolidation roadmap and goals

9. Monitoring & Incident Response (docs/monitoring-incident/)

Overview: Monitoring standards and incident response procedures.

Content Source: Includes runbooks from egi-engine

Pages:

  • index.md - Overview of monitoring and incident response philosophy
  • monitoring-standards.md - Uptime Kuma and CrowdSec setup standards
  • health-checks.md - Health check implementation expectations
  • alert-routing.md - Slack alert configuration and routing rules
  • outage-response.md - Step-by-step outage response procedures
  • degraded-service.md - Handling degraded performance scenarios
  • rollback-procedures.md - When and how to rollback changes
  • incident-response.md - Comprehensive incident handling workflow
  • postmortem-template.md - Incident postmortem format and requirements
  • runbooks/ - Operational runbooks (migrated from egi-engine docs/runbooks/)

10. Onboarding & Offboarding (docs/onboarding-offboarding/)

Overview: Employee lifecycle procedures.

Pages:

  • index.md - Overview of onboarding and offboarding processes
  • employee-setup.md - New employee onboarding workflow
  • account-access.md - Account provisioning checklist across all systems
  • tools-required.md - Required tools and access for each role
  • documentation-expectations.md - Documentation standards for new team members
  • offboarding-procedures.md - Handoff, access removal, and cleanup on departure

11. Migration & Archival (docs/migration-archival/)

Overview: System migration and archival procedures.

Pages:

  • index.md - Overview of migration and archival philosophy
  • system-migration.md - How to plan and execute system migrations
  • domain-cutover.md - DNS and domain migration procedures
  • backup-verification.md - Backup validation and testing procedures
  • rollback-planning.md - Migration rollback strategies and preparation
  • legacy-labeling.md - How to properly mark and document legacy systems
  • archival-procedures.md - Safe system archival and decommissioning

12. Reference Library (docs/reference-library/)

Overview: Templates, checklists, glossary, and quick references.

Pages:

  • index.md - Overview of reference materials
  • glossary.md - Company terminology and definitions
  • naming-conventions.md - Naming standards across all systems
  • metadata-schema.md - Metadata standards and schema
  • templates/ - All document templates (see Templates section below)
  • checklists/ - Standalone operational checklists
  • links.md - Important links and resource directory

Templates

Location: docs/reference-library/templates/

Each template is a markdown file with:

  • Clear sections with placeholder text and guidance
  • Instructions in callouts or comments
  • Examples where helpful
  • Frontmatter metadata (title, description, last_updated)

Required Templates

1. sop-template.md - Standard Operating Procedure

  • Purpose and scope
  • Prerequisites
  • Procedure steps (numbered)
  • Verification steps
  • Troubleshooting common issues
  • Related documentation links

2. system-profile-template.md - System Documentation

  • System overview and purpose
  • Technology stack and dependencies
  • Deployment architecture
  • Monitoring and alerting setup
  • Authentication and access control
  • Runbooks and operational procedures
  • Key contacts and ownership

3. execution-brief-template.md - Project Execution Brief

  • Project objective and background
  • Scope (in scope / out of scope)
  • Stakeholders and roles
  • Timeline and milestones
  • Deliverables
  • Risks and mitigation strategies
  • Success criteria

4. incident-report-template.md - Post-Incident Report

  • Incident summary
  • Timeline of events
  • Impact assessment (users, systems, revenue)
  • Root cause analysis
  • Resolution steps taken
  • Action items and owners
  • Postmortem findings

5. migration-checklist.md - System Migration Checklist

  • Pre-migration tasks and preparation
  • Migration execution steps
  • Validation and verification steps
  • Rollback plan and triggers
  • Post-migration monitoring
  • Communication plan

6. domain-cutover-checklist.md - Domain/DNS Cutover

  • DNS preparation and TTL reduction
  • Cutover execution steps
  • Verification procedures
  • Rollback procedures
  • Post-cutover monitoring
  • Communication timeline

7. repo-audit-checklist.md - Repository Audit

  • Documentation completeness
  • Test coverage
  • CI/CD pipeline verification
  • Security scanning
  • Dependency updates
  • Standards compliance
  • License verification

8. product-launch-checklist.md - Product Launch

  • Pre-launch tasks (analytics, monitoring, documentation, testing)
  • Launch execution steps
  • Post-launch monitoring and validation
  • Communication plan
  • Rollback criteria

9. client-onboarding-checklist.md - Client Onboarding

  • Kickoff meeting agenda
  • Access provisioning steps
  • Documentation requirements
  • Handoff procedures
  • Support setup and SLA establishment

10. uptime-monitoring-checklist.md - Uptime Kuma Setup

  • Service identification and endpoints
  • Health check configuration
  • Alert threshold configuration
  • Slack integration setup
  • Verification and testing
  • Documentation requirements

Blog & Versioning

Blog/Changelog

Location: blog/

Purpose:

  • Announce major SOP updates and policy changes
  • Document significant operational or tooling changes
  • Provide historical record of changes
  • Complement Slack announcements with permanent, searchable records

Structure:

  • Standard Docusaurus blog posts
  • Date-based URLs (e.g., /blog/2026/03/25/new-crowdsec-standard)
  • Categories/tags: sop-update, policy-change, tooling, security, process
  • Author attribution
  • Automatic RSS feed generation

Example Post Types:

  • "New CrowdSec Intrusion Detection Standard" - announcing security requirement
  • "Updated SKU Naming Conventions v2.1" - major standards update
  • "Migration to ERPNext Complete" - tooling change announcement
  • "New Client Delivery Process" - process updates

Relationship to Slack:

  • Blog posts for formal, permanent announcements
  • Slack for day-to-day updates and discussions
  • Link to blog posts from Slack announcements
  • Blog provides searchable, archival record

Versioning Strategy

Approach: Lightweight Versioning

Rather than maintaining multiple version snapshots, we use a lightweight approach:

Current State:

  • All documentation in docs/ represents the current, authoritative state
  • "Last Updated" date in page frontmatter
  • Critical documents (like SKU standards) include a "Changelog" section

Historical Tracking:

  • Git history provides point-in-time snapshots
  • Link to specific git commits when "as of X date" references are needed
  • Blog posts document when and why changes were made

Rationale:

  • SOPs should reflect current operational state, not historical versions
  • Full versioning creates maintenance burden (updating multiple versions)
  • Git already provides complete version history
  • Most users need current state, not historical comparisons

Future Migration:

  • Can add full Docusaurus versioning later if needed
  • Starting lightweight reduces complexity and maintenance burden

Deployment & GitOps

Git Repository

Repository: egi-sop/ (new git repository)

Branching Strategy:

  • Main branch: main (production, protected)
  • Feature branches: feature/section-name or update/topic-name
  • Pull request workflow: All changes reviewed via PRs before merging

Branch Protection:

  • Require PR approval before merging to main
  • Require status checks to pass (build verification)
  • Prevent force pushes to main

Vercel Deployment

Setup:

  1. Connect git repository to Vercel
  2. Framework preset: Docusaurus
  3. Build command: npm run build
  4. Output directory: build
  5. Node version: LTS (18.x or later)

Automatic Deployments:

  • Production: Commits to main → automatic deployment to production URL
  • Preview: Pull requests → preview deployments with unique URLs
  • Branch previews: Optional branch-based previews for testing

Environment Variables:

  • NODE_ENV=production for production builds
  • Future API keys or secrets managed via Vercel environment variables

Custom Domain:

  • Configure custom domain in Vercel (e.g., sop.egintegrations.com)
  • SSL/TLS automatically provisioned and managed
  • Cloudflare integration for DNS management

GitOps Workflow

1. Developer creates feature branch from main
2. Makes documentation updates locally
3. Tests changes with `npm run start` (local preview)
4. Commits changes with descriptive message
5. Pushes branch and opens pull request
6. Team reviews via PR comments + Vercel preview link
7. Approved PR merges to main
8. Vercel automatically deploys to production
9. Team notified via Slack (optional webhook integration)

CI/CD Pipeline

Vercel Handles:

  • Build execution
  • Deployment to production/preview environments
  • SSL/TLS management
  • CDN distribution

Optional GitHub Actions:

  • Markdown linting (markdownlint)
  • Link checking (verify no broken links)
  • Spell checking
  • Build verification (run before merge)

Rollback Procedures

Vercel Dashboard:

  • Maintains deployment history
  • One-click rollback to any previous deployment
  • Instant rollback (no rebuild required)

Git Rollback:

  • git revert commit that caused issue
  • Push to main for automatic redeployment
  • Creates audit trail of rollback

Maintenance & Contribution

Contribution Workflow

Target Audience: Technical team comfortable with git and markdown

Workflow:

  1. Clone repository: git clone <repo-url>
  2. Install dependencies: npm install
  3. Create feature branch: git checkout -b feature/topic-name
  4. Make changes: Edit markdown files in preferred editor
  5. Test locally: npm run start for live preview at http://localhost:3000
  6. Commit changes: Clear, descriptive commit messages
  7. Push branch: git push origin feature/topic-name
  8. Open pull request: Via GitHub/GitLab interface
  9. Review: Team reviews via PR comments and Vercel preview link
  10. Merge: Approved PRs merge to main, auto-deploy to production

README.md Contents

The repository README will include:

Getting Started:

  • Repository overview and purpose
  • Clone and setup instructions
  • Running locally (npm install, npm run start)
  • Building for production (npm run build)

Project Structure:

  • Directory organization overview
  • Where to find specific content types
  • How sections map to URLs

Making Changes:

  • How to add new pages
  • How to update existing content
  • How to add images and static assets
  • Frontmatter requirements

Sidebar Management:

  • How to update sidebars.js
  • Adding new sections or pages to navigation
  • Ordering and nesting structure

Blog Posts:

  • How to create changelog/announcement posts
  • Frontmatter requirements for blog posts
  • Tagging and categorization

Deployment:

  • GitOps workflow explanation
  • How preview deployments work
  • How to rollback changes

Troubleshooting:

  • Common build errors and solutions
  • Local development issues
  • Link checking and validation

Contribution Guidelines:

  • Markdown conventions
  • Frontmatter standards
  • Writing style guide
  • PR review expectations

Markdown Conventions

Frontmatter:

---
title: Page Title
description: Brief description for SEO and previews
last_updated: 2026-03-25
tags: [tag1, tag2]
---

Heading Hierarchy:

  • H1 (#) for page title (usually in frontmatter, not body)
  • H2 (##) for main sections
  • H3 (###) for subsections
  • H4+ for further nesting (use sparingly)

Code Blocks:

# Use language hints for syntax highlighting
npm install

Admonitions:

:::tip
Helpful tips and best practices
:::

:::warning
Important warnings or caveats
:::

:::info
Additional information or context
:::

:::danger
Critical warnings or breaking changes
:::

Internal Links:

  • Use relative paths: [Link Text](../section/page.md)
  • Docusaurus automatically resolves to correct URLs

Images:

  • Store in static/img/
  • Reference as: ![Alt text](/img/filename.png)

AI-Assisted Contributions

The team can leverage AI tools (Claude, ChatGPT, etc.) for:

  • Drafting new SOP content based on discussions
  • Updating existing documentation for clarity
  • Generating checklists and templates
  • Reviewing documentation for completeness and consistency
  • Suggesting improvements to existing content

Process:

  1. Use AI to draft or update content
  2. Review and refine AI-generated content
  3. Follow normal PR workflow for review
  4. Human approval required before merging

Ongoing Maintenance

Regular Reviews:

  • Quarterly review of documentation for outdated content
  • Update "last_updated" frontmatter when editing
  • Archive deprecated procedures
  • Verify tool references are still current

Content Updates:

  • Update blog with major changes
  • Keep tooling stack documentation current
  • Maintain templates as processes evolve
  • Refresh examples to reflect current patterns

Link Maintenance:

  • Periodic link checking (manual or automated)
  • Update external links that have moved
  • Fix broken internal links

Version Updates:

  • Keep Docusaurus and dependencies updated
  • Test updates in preview environment before deploying
  • Monitor Docusaurus changelog for breaking changes

Implementation Plan Reference

This design document will be followed by a detailed implementation plan that breaks down the work into executable tasks. The implementation plan will cover:

  1. Project initialization and dependency setup
  2. Docusaurus configuration and branding
  3. Content migration from egi-engine and egi-ci:cd
  4. Template creation
  5. Blog setup and initial posts
  6. Testing and validation
  7. Deployment to Vercel
  8. Documentation and handoff

Success Criteria

The project will be considered complete when:

  1. Structure: All 12 documentation sections created with proper navigation
  2. Content: Existing documentation migrated from egi-engine and egi-ci:cd
  3. Updates: All tool references updated to reflect consolidated stack
  4. Templates: All 10 required templates created and documented
  5. Branding: EGI branding applied (colors, typography, logo)
  6. Blog: Blog setup with example posts
  7. Deployment: Site deployed to Vercel with GitOps workflow
  8. Documentation: README and contribution guidelines complete
  9. Testing: All links work, site builds without errors, search functional
  10. Handoff: Team trained on contribution workflow

Open Questions & Future Enhancements

Resolved:

  • All major design questions resolved during brainstorming

Future Enhancements (Post-Launch):

  • Add authentication (Vercel password protection or SSO)
  • Integrate Algolia search if local search is insufficient
  • Add GitHub Actions for automated linting and link checking
  • Create Slack webhooks for deployment notifications
  • Add analytics (PostHog or Vercel Analytics)
  • Create custom React components for common patterns
  • Full versioning if historical documentation becomes necessary

Appendix

Technology Stack

  • Framework: Docusaurus v2 (latest)
  • Runtime: Node.js LTS (18.x+)
  • Package Manager: npm
  • Hosting: Vercel
  • Version Control: Git (GitHub or GitLab)
  • Search: Docusaurus local search plugin

References