Documentation
Introduction

Introduction

XeoContext is a modern "System Design" visualization tool. It is designed to be a lightweight, self-contained viewer for:

  • System Design documents: Markdown files with Mermaid diagram support.
  • OpenAPI definitions: visualized using Swagger UI.
  • AsyncAPI definitions: visualized using AsyncAPI React component.

XeoContext is designed to be deployed as a Docker container with a read-only volume mounted to provide the content.

Features

Core Viewers

  • System Design Viewer:
    • Renders Markdown documents with GitHub Flavored Markdown (GFM).
    • Mermaid Diagrams: Native support for Flowcharts, Sequence diagrams, C4 diagrams, classes, and more.
    • Smart Navigation: Recursive sidebar navigation with support for nested items.
    • SEO Optimized: dynamic document title and description updates based on frontmatter.
  • OpenAPI Viewer:
    • Interactive REST API documentation using a custom implementation of Swagger UI.
    • Dark Mode Support: Fully customized theme that adapts to the application's dark mode.
    • Server-Side Dereferencing: Resolves all $ref pointers (internal and external) to ensure stability.
  • AsyncAPI Viewer:
    • Event-Driven Architecture visualization using the AsyncAPI React component.
    • Supports dereferencing of AsyncAPI schemas from external URLs.

Architecture & Experience

  • Theme Support: Seamless switching between Light, Dark, and System modes.
  • Dynamic Content: Content is decoupled from code. Loads configuration and documentation from local files or Git repositories.
  • Docker Ready:
    • Production-optimized image (xeost/xeocontext:latest).
    • Live-reload image for development (xeost/xeocontext-live-reload:latest).
  • Customizable Deployment: Built-in scripts (setup-content) to easily deploy your own instance to Vercel or other platforms, syncing content from your own repository.
  • Modern Stack: Built with Next.js 16 (App Router) and Turbopack.

AI Integration

This repository is designed to be the "Source of Truth" for system design. The content directory is intended to be read by AI Coding Agents (via MCP Servers or direct access) to scaffold and maintain other repositories based on the designs defined here. But from a clean system design content repository, see examples/markdown-openapi-asyncapi (opens in a new tab) for a quickstart.

Setup & Installation