{"id":35211119,"url":"https://github.com/xeost/xeocontext","last_synced_at":"2026-05-20T09:39:33.226Z","repository":{"id":329266621,"uuid":"1117342870","full_name":"xeost/xeocontext","owner":"xeost","description":"XeoContext App.","archived":false,"fork":false,"pushed_at":"2025-12-31T00:13:37.000Z","size":551,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T20:17:15.074Z","etag":null,"topics":["api-documentation","asyncapi","docker","docs-as-code","documentation","domain-driven-design","mermaid-js","nextjs","openapi","software-architecture","system-design","visualization"],"latest_commit_sha":null,"homepage":"https://xeocontext.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xeost.png","metadata":{"files":{"readme":"README.md","changelog":"changelogs/v0.1.1.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-16T07:18:28.000Z","updated_at":"2025-12-31T00:13:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xeost/xeocontext","commit_stats":null,"previous_names":["xeost/xeocontext"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/xeost/xeocontext","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeost%2Fxeocontext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeost%2Fxeocontext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeost%2Fxeocontext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeost%2Fxeocontext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xeost","download_url":"https://codeload.github.com/xeost/xeocontext/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xeost%2Fxeocontext/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33253749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-20T04:48:54.280Z","status":"ssl_error","status_checked_at":"2026-05-20T04:48:10.851Z","response_time":356,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-documentation","asyncapi","docker","docs-as-code","documentation","domain-driven-design","mermaid-js","nextjs","openapi","software-architecture","system-design","visualization"],"created_at":"2025-12-29T18:24:57.772Z","updated_at":"2026-05-20T09:39:33.220Z","avatar_url":"https://github.com/xeost.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![XeoContext Header](xeocontext.webp)\n\n# XeoContext\n\nXeoContext is a modern \"System Design\" visualization tool. It is designed to be a lightweight, self-contained viewer for:\n\n- **System Design documents**: Markdown files with Mermaid diagram support.\n- **OpenAPI definitions**: visualized using Swagger UI.\n- **AsyncAPI definitions**: visualized using AsyncAPI React component.\n\nXeoContext is designed to be deployed as a Docker container with a read-only volume mounted to provide the content.\n\n## Table of Contents\n\n- [Features](#features)\n- [AI Integration](#ai-integration)\n- [Usage with Live-reload](#usage-with-live-reload)\n- [Production Usage (without Live-reload)](#production-usage-without-live-reload)\n- [Deployment on Vercel](#deployment-on-vercel)\n  - [Maintaining Your Deployment](#maintaining-your-deployment)\n- [Development (Contributing)](#development-contributing)\n- [Content Configuration](#content-configuration)\n  - [Why Domain-Driven Structure?](#why-domain-driven-structure)\n  - [Directory Structure](#directory-structure)\n  - [The xeocontext.config.json file](#the-xeocontextconfigjson-file)\n  - [The .agent/rules/content.md file](#the-agentrulescontentmd-file)\n- [Extra Tips](#extra-tips)\n  - [Content Validation](#content-validation)\n\n## Features\n\n### Core Viewers\n\n- **System Design Viewer**:\n  - Renders Markdown documents with GitHub Flavored Markdown (GFM).\n  - **Mermaid Diagrams**: Native support for Flowcharts, Sequence diagrams, C4 diagrams, classes, and more.\n  - **Smart Navigation**: Recursive sidebar navigation with support for nested items.\n  - **SEO Optimized**: dynamic document title and description updates based on frontmatter.\n- **OpenAPI Viewer**:\n  - Interactive REST API documentation using a custom implementation of **Swagger UI**.\n  - **Dark Mode Support**: Fully customized theme that adapts to the application's dark mode.\n  - **Server-Side Dereferencing**: Resolves all `$ref` pointers (internal and external) to ensure stability.\n- **AsyncAPI Viewer**:\n  - Event-Driven Architecture visualization using the AsyncAPI React component.\n  - Supports dereferencing of AsyncAPI schemas from external URLs.\n\n### Architecture \u0026 Experience\n\n- **Theme Support**: Seamless switching between Light, Dark, and System modes.\n- **Dynamic Content**: Content is decoupled from code. Loads configuration and documentation from local files or Git repositories.\n- **Docker Ready**:\n  - Production-optimized image (`xeost/xeocontext:latest`).\n  - Live-reload image for development (`xeost/xeocontext-live-reload:latest`).\n- **Customizable Deployment**: Built-in scripts (`setup-content`) to easily deploy your own instance to Vercel or other platforms, syncing content from your own repository.\n- **Modern Stack**: Built with Next.js 16 (App Router) and Turbopack.\n\n## AI Integration\n\nThis 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`](examples/markdown-openapi-asyncapi) for a quickstart.\n\n## Usage with Live-reload\n\nFor a quick start with a pre-configured environment, you can use the [XeoContext Template](https://github.com/xeost/xeocontext-template).\n\n1. **Clone the template:**\n   ```bash\n   git clone https://github.com/xeost/xeocontext-template my-system-design\n   cd my-system-design\n   ```\n\n2. **Run with Docker Compose:**\n   The template includes a `docker-compose.yml` configured to use the `xeost/xeocontext-live-reload:latest` image.\n   ```bash\n   docker compose up -d\n   ```\n\n3. **Edit Content:**\n   Modify the files in the `content` directory. The viewer will automatically reload to reflect your changes. See [Content Configuration](#content-configuration) for more details.\n\n**AI Support:**\nThe template includes `.agent/rules/content.md`, which provides instructions for LLMs on how to structure the design content (DDD, OpenAPI, AsyncAPI).\n\n\u003e **Note:** The template provides a minimal starting point. For comprehensive examples of directory structures and configurations, please refer to the [`examples`](examples) directory in this repository.\n\n## Production Usage (without Live-reload)\n\nIf your content is static and will not be edited, you can switch to the production-optimized image for better performance.\n\n1.  Follow the steps in the [Usage with Live-reload](#usage-with-live-reload) section to set up your repository.\n2.  Edit the `docker-compose.yml` file and change the image name:\n\n    ```yaml\n    services:\n      xeocontext:\n        image: xeost/xeocontext:latest # Change from xeocontext-live-reload\n        # ... rest of the configuration\n    ```\n\n## Deployment on Vercel\n\nThis workflow allows you to deploy a customized version of XeoContext (with your embedded content) to Vercel.\n\n1.  **Clone the XeoContext Viewer:**\n    Start by cloning the base viewer repository.\n    ```bash\n    git clone https://github.com/xeost/xeocontext.git my-viewer\n    cd my-viewer\n    pnpm install\n    ```\n\n2.  **Check Available Versions:**\n    See which versions of XeoContext are available to pin your deployment to.\n    ```bash\n    pnpm list-releases\n    ```\n\n3.  **Create Deployment Repository:**\n    Create a new empty repository on GitHub (e.g., `github-user/system-design-example`) where your customized viewer will live.\n\n4.  **Configure Environment:**\n    Copy `.env.example` to `.env` and set the following variables:\n    ```bash\n    cp .env.example .env\n    ```\n\n    - **`XEOCONTEXT_CONTENT_TYPE`**: Set to `'local'` (if content is on your machine) or `'git'` (if content is in a remote repo).\n    - **`XEOCONTEXT_CONTENT_SOURCE`**: Path to local directory (relative or absolute) or Git URL of your content repository.\n    - **`XEOCONTEXT_TAG`**: The XeoContext version tag you want to use (e.g., `v0.1.0`).\n    - **`XEOCONTEXT_DEPLOY_REPO`**: The URL of the GitHub repository you created in step 3.\n\n5.  **Sync \u0026 Setup:**\n    Run the setup script. This will reset the code to the specified tag, copy your content into the `content` directory, and configure the git remotes (`upstream` for updates, `origin` for your deployment).\n    ```bash\n    pnpm setup-content\n    ```\n\n6.  **Push to GitHub:**\n    Commit the changes and push to your deployment repository.\n    ```bash\n    git add .\n    git commit -m \"Initial deployment\"\n    git push -u origin main\n    ```\n    *Note: Connect this repository to Vercel for automatic deployments.*\n\n### Maintaining Your Deployment\n\n**Updating XeoContext Version:**\nIf a new version of XeoContext is released:\n1. Update `XEOCONTEXT_TAG` in your `.env` file.\n2. Run `pnpm setup-content`.\n3. Commit and push.\n\n**Updating Content:**\nIf you change your design content (in your local folder or external content repo):\n1. Run `pnpm setup-content`.\n2. Commit and push.\n\n## Development (Contributing)\n\n1. **Install dependencies:**\n   ```bash\n   pnpm install\n   ```\n2. **Configure Environment:**\n   Copy `.env.example` to `.env` and configure `XEOCONTEXT_CONTENT_DIR` to point to a sample content directory.\n   ```bash\n   cp .env.example .env\n   ```\n   Open `.env` and uncomment/set:\n   ```env\n   XEOCONTEXT_CONTENT_DIR=./examples/markdown-openapi-asyncapi\n   ```\n\n3. **Run development server:**\n   ```bash\n   pnpm dev\n   ```\n4. **Open Application:**\n   Navigate to [http://localhost:12051](http://localhost:12051).\n\n## Content Configuration\n\nThe application reads from the `/content` directory (or the value of `XEOCONTEXT_CONTENT_DIR` in the environment).\n\n### Why Domain-Driven Structure?\n\nOrganizing your design content by **Domain** (e.g., `identity`, `payments`) rather than by file type is crucial for effective AI-assisted development. This approach creates clear **Context Boundaries**, allowing you to feed an AI agent the complete \"truth\" about a specific domain—its business logic (Markdown), API contracts (OpenAPI), and events (AsyncAPI)—without distracting noise.\n\nFor a deeper dive into this philosophy, read [Harmonizing AI Code Generation with Centralized System Design](https://xeost.com/blog/centralizing-system-design).\n\n### Directory Structure\n\nThe content directory follows a strict separation between **Global Architecture** and **Bounded Contexts (Domains)**.\n\n**1. Root Configuration**\n- `xeocontext.config.json`: [MANDATORY] The central navigation and metadata map for the viewer.\n\n**2. The \"Global\" Directory (`/global`)**\nDefines the laws of the system and cross-cutting concerns.\n- **Gateway (`/global/gateway`)**: Contains the **Master Root** files (`openapi.yaml`, `asyncapi.yaml`). These files aggregate endpoints and channels from all domains to provide a unified \"System View\".\n- **ADRs (`/global/adrs`)**: Architecture Decision Records explaining *why* decisions were made.\n- **Standards (`/global/standards`)**: Naming conventions, error handling, etc.\n\n**3. Domain Modules (`/domains`)**\nEach folder represents a specific business capability (e.g., `identity`, `payments`).\n- **Co-location**: Markdown, OpenAPI, and AsyncAPI specs reside together.\n- **Fragmented Architecture**: Actual definitions (Schemas, Paths) should live in `components/` subfolders and be aggregated by the domain's root `openapi.yaml`.\n\n```text\n/content\n├── xeocontext.config.json        # [MANDATORY] Main configuration\n├── global/                       # [MANDATORY] Cross-cutting architecture\n│   ├── gateway/                  # Unified System API (Master Roots)\n│   │   ├── openapi.yaml          # Imports from all domains\n│   │   └── asyncapi.yaml\n│   ├── adrs/                     # Architecture Decision Records\n│   └── standards/                # Global Standards\n└── domains/                      # [MANDATORY] Business Logic\n    ├── {domain-name}/            # e.g., identity, payments\n    │   ├── readme.md             # Domain overview\n    │   ├── openapi.yaml          # Domain-specific API Root\n    │   ├── asyncapi.yaml         # Domain-specific Event Root\n    │   └── components/           # Reusable schemas \u0026 paths\n    │       ├── schemas/\n    │       └── paths/\n```\n\n### The `xeocontext.config.json` file\n\nThis file controls the global settings and navigation sidebar of the application.\n\n- **`projectName`**: Displayed in the header.\n- **`projectDomain`**: Optional domain name.\n- **`navigation`**: An array of sections that defines the **System Design** sidebar.\n  - **`title`**: Section header.\n  - **`items`**: Link items. Supports up to **3 nested levels**.\n    - **`title`**: Link text.\n    - **`href`**: Path to the Markdown file (relative to `content`, without `.md` extension). **Important**: The application maps the URL path `/content/some/path` to the file `/content/some/path.md` OR `/content/some/path/readme.md`.\n    - **`items`**: (Optional) Sub-items for creating nested menus.\n- **`openapi`**: Path to the main OpenAPI definition file. If present, an \"OpenAPI\" tab will appear in the UI.\n- **`asyncapi`**: Path to the main AsyncAPI definition file. If present, an \"AsyncAPI\" tab will appear in the UI.\n\n```json\n{\n    \"projectName\": \"ExampleApp\",\n    \"projectDomain\": \"exampleapp.com\",\n    \"navigation\": [\n        {\n            \"title\": \"System Architecture\",\n            \"items\": [\n                { \"title\": \"Overview\", \"href\": \"/\" },\n                { \"title\": \"Infrastructure \u0026 HA\", \"href\": \"/global/infrastructure\" },\n                { \"title\": \"Security\", \"href\": \"/global/security\" },\n                { \"title\": \"Database Schema\", \"href\": \"/global/database\" },\n                { \"title\": \"Workflows\", \"href\": \"/global/workflows\" }\n            ]\n        },\n        {\n            \"title\": \"Standards \u0026 ADRs\",\n            \"items\": [\n                { \"title\": \"API Standards\", \"href\": \"/global/standards/api-design\" },\n                { \"title\": \"Error Handling\", \"href\": \"/global/standards/error-handling\" },\n                { \"title\": \"Code Conventions\", \"href\": \"/global/standards/code-conventions\" },\n                { \"title\": \"ADR 001 - DDD\", \"href\": \"/global/adrs/001-domain-driven-design\" },\n                { \"title\": \"ADR 002 - Local First\", \"href\": \"/global/adrs/002-local-first-sync\" },\n                { \"title\": \"ADR 003 - K8s\", \"href\": \"/global/adrs/003-k8s-infrastructure\" }\n            ]\n        },\n        {\n            \"title\": \"Domains\",\n            \"items\": [\n                { \"title\": \"Identity\", \"href\": \"/domains/identity\" },\n                { \"title\": \"Todos\", \"href\": \"/domains/todos\" },\n                { \"title\": \"Notes\", \"href\": \"/domains/notes\" },\n                { \"title\": \"Library (Sync)\", \"href\": \"/domains/library\" }\n            ]\n        }\n    ],\n    \"openapi\": \"/global/gateway/openapi.yaml\",\n    \"asyncapi\": \"/global/gateway/asyncapi.yaml\"\n}\n```\n\n### The `.agent/rules/content.md` file\n\nThis file contains crucial instructions for Large Language Models (LLMs) to understand how to structure and generate content within your user design repository (a repository containing only Markdown, OpenAPI, AsyncAPI, and a `docker-compose.yml`).\n\nIt defines the **Domain-Driven Structure**, naming conventions, and best practices for creating cohesive system designs.\n\n**Compatibility:**\n- **Local AI Agents**: This file is automatically detected by agents following the `.agent` convention.\n- **Windsurf / Cursor**: You can easily adapt these rules for popular AI code editors by copying the content to their respective rule configuration locations (e.g., `.windsurf/rules/content.md` or `.cursor/rules/content.md`).\n\n\n## Extra Tips\n\n### Content Validation\n\nIt is recommended to validate your spec files before committing changes to ensure the viewer renders them correctly.\n\n#### OpenAPI Validation\nYou can use [Redocly CLI](https://redocly.com/docs/cli/) to lint and bundle your OpenAPI definitions.\n\n```bash\n# Lint the main gateway file (and all its references)\npnpm --package=@redocly/cli dlx redocly lint content/global/gateway/openapi.yaml\n\n# Lint a specific domain file\npnpm --package=@redocly/cli dlx redocly lint content/domains/identity/components/paths/auth_login.yaml\n```\n\n#### AsyncAPI Validation\nYou can use [AsyncAPI CLI](https://www.asyncapi.com/docs/tools/cli) to validate your AsyncAPI definitions.\n\n```bash\n# Validate the main gateway file\npnpm dlx @asyncapi/cli validate content/global/gateway/asyncapi.yaml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxeost%2Fxeocontext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxeost%2Fxeocontext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxeost%2Fxeocontext/lists"}