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
- Example:
- Blog:
/blog/[slug]- Example:
/blog/2026/03/25/new-crowdsec-standard
- Example:
- Custom Pages:
/[page]- Example:
/(homepage)
- Example:
Navigation
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/ordocs/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 philosophycommunication-standards.md- Internal communication expectationsslack-conventions.md- Slack usage, channel naming, threading rules, notification etiquetteownership-model.md- Ownership expectations and accountability frameworkdocumentation-standards.md- Documentation requirements and best practicesworkflow-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 standardsrepo-conventions.md- Repository naming, structure, README requirements (from egi-ci:cd)development-workflow.md- Development standards, branching, commit messagesapproval-gates.md- Code review and approval requirementsrelease-procedures.md- How to release software safelyrollback-procedures.md- How to safely rollback releasesdocumentation-requirements.md- Per-repo documentation standardsai-assisted-development.md- Standards and best practices for working with AI toolsarchitecture.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 operationsproduct-lifecycle.md- Product stages from concept to sunsetlaunch-checklist.md- Pre-launch requirements and validationrelease-checklist.md- Release process and verificationanalytics-instrumentation.md- PostHog setup and instrumentation standardsfeature-flags.md- Feature flag usage, conventions, and lifecyclesupport-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 philosophyonboarding-workflow.md- How to onboard new clientsdocumentation-expectations.md- Client-facing documentation standardshandoff-procedures.md- Transitioning projects to clientsdeployment-standards.md- Deployment expectations and patterns for client projectsownership-model.md- Post-delivery ownership and responsibility modelsupport-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 rulesplatform-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 releasesexamples.md- Real-world SKU examples with explanationstooling.md- Links to gen_sku.py and sku_audit.py in egi-engine repoupdate-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 philosophypricing-methodology.md- How pricing is determined and calculatedestimation-standards.md- Quoting and estimation best practicespackaging-rules.md- How to package services and productsstripe-integration.md- Stripe payment integration patterns and standardscalculator-reference.md- Pricing calculator usage and maintenancepricing-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 philosophyslack.md- Purpose, usage patterns, channel conventions, integrationserpnext.md- ERP usage, workflows, and best practicesposthog.md- Analytics setup, event tracking, and analysiscloudflare.md- DNS management, security features, CDN usageuptime-kuma.md- Monitoring setup, alerting configuration, procedurescrowdsec.md- Intrusion detection setup, response procedures, maintenancedocusaurus.md- This documentation system, contribution workflowvercel.md- Deployment platform, configuration, best practicespenpot.md- Design tool usage, file organization, collaborationstripe.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 managementauth-patterns.md- Current authentication implementations across systemsaccess-expectations.md- Internal access policies and principlesdocumenting-auth.md- How to document authentication per systemaccount-provisioning.md- Account setup and provisioning proceduresfuture-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 philosophymonitoring-standards.md- Uptime Kuma and CrowdSec setup standardshealth-checks.md- Health check implementation expectationsalert-routing.md- Slack alert configuration and routing rulesoutage-response.md- Step-by-step outage response proceduresdegraded-service.md- Handling degraded performance scenariosrollback-procedures.md- When and how to rollback changesincident-response.md- Comprehensive incident handling workflowpostmortem-template.md- Incident postmortem format and requirementsrunbooks/- Operational runbooks (migrated from egi-enginedocs/runbooks/)
10. Onboarding & Offboarding (docs/onboarding-offboarding/)
Overview: Employee lifecycle procedures.
Pages:
index.md- Overview of onboarding and offboarding processesemployee-setup.md- New employee onboarding workflowaccount-access.md- Account provisioning checklist across all systemstools-required.md- Required tools and access for each roledocumentation-expectations.md- Documentation standards for new team membersoffboarding-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 philosophysystem-migration.md- How to plan and execute system migrationsdomain-cutover.md- DNS and domain migration proceduresbackup-verification.md- Backup validation and testing proceduresrollback-planning.md- Migration rollback strategies and preparationlegacy-labeling.md- How to properly mark and document legacy systemsarchival-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 materialsglossary.md- Company terminology and definitionsnaming-conventions.md- Naming standards across all systemsmetadata-schema.md- Metadata standards and schematemplates/- All document templates (see Templates section below)checklists/- Standalone operational checklistslinks.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-nameorupdate/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:
- Connect git repository to Vercel
- Framework preset: Docusaurus
- Build command:
npm run build - Output directory:
build - 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=productionfor 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 revertcommit that caused issue- Push to
mainfor automatic redeployment - Creates audit trail of rollback
Maintenance & Contribution
Contribution Workflow
Target Audience: Technical team comfortable with git and markdown
Workflow:
- Clone repository:
git clone <repo-url> - Install dependencies:
npm install - Create feature branch:
git checkout -b feature/topic-name - Make changes: Edit markdown files in preferred editor
- Test locally:
npm run startfor live preview athttp://localhost:3000 - Commit changes: Clear, descriptive commit messages
- Push branch:
git push origin feature/topic-name - Open pull request: Via GitHub/GitLab interface
- Review: Team reviews via PR comments and Vercel preview link
- 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:

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:
- Use AI to draft or update content
- Review and refine AI-generated content
- Follow normal PR workflow for review
- 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:
- Project initialization and dependency setup
- Docusaurus configuration and branding
- Content migration from egi-engine and egi-ci:cd
- Template creation
- Blog setup and initial posts
- Testing and validation
- Deployment to Vercel
- Documentation and handoff
Success Criteria
The project will be considered complete when:
- Structure: All 12 documentation sections created with proper navigation
- Content: Existing documentation migrated from egi-engine and egi-ci:cd
- Updates: All tool references updated to reflect consolidated stack
- Templates: All 10 required templates created and documented
- Branding: EGI branding applied (colors, typography, logo)
- Blog: Blog setup with example posts
- Deployment: Site deployed to Vercel with GitOps workflow
- Documentation: README and contribution guidelines complete
- Testing: All links work, site builds without errors, search functional
- 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
- Docusaurus documentation: https://docusaurus.io
- Vercel deployment guide: https://vercel.com/docs
- EGI website (branding): https://egintegrations.com
- Source repositories:
- egi-engine:
~/Developer/egi-engine - egi-ci💿
~/Developer/egi-ci:cd
- egi-engine: