# department-of-veterans-affairs/ves-event-bus-developer-portal architecture

> Architecture diagram of the GitHub repository department-of-veterans-affairs/ves-event-bus-developer-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/department-of-veterans-affairs/ves-event-bus-developer-portal
- Repository: https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal

## Overview

1. **Repository purpose**
   - This repo is a **documentation portal**, not an application backend. It publishes the public-facing **Enterprise Event Bus Developer Portal** for the VA.
   - The primary output is a **static website** hosted on GitHub Pages at the URL in the README.

2. **Core architectural boundary**
   - The main boundary is between **source documentation** and **generated HTML site**.
   - Markdown content in `docs/` is the authoritative source; MkDocs transforms it into the rendered portal.

3. **Content layer**
   - `docs/` contains the actual product documentation, organized as topic-based pages such as:
     - event-driven architecture intro
     - producing/consuming events
     - onboarding for producers and consumers
     - environments, terminology, support, and offboarding
   - This is the user-facing knowledge layer of the portal.

4. **Site generation layer**
   - `mkdocs.yml` defines the site structure, navigation, theme, and build behavior.
   - The repo uses **MkDocs** with **MkDocs Material** to render the Markdown into a navigable static documentation site.

5. **Styling and presentation**
   - Custom presentation tweaks live in `docs/stylesheets/`.
   - These styles augment the MkDocs theme and are part of the presentation layer, not the content itself.

6. **Media and rich content**
   - `docs/img/` and `docs/videos/` hold diagrams, images, and embedded video assets used by the documentation pages.
   - These assets are delivered as static files alongside the generated site.

7. **Development workflow**
   - Local authoring is Python-based: install dependencies from `requirements-lock.txt`, then run `mkdocs serve`.
   - The local dev server provides a live preview of the site while editing Markdown and assets.

8. **Publishing flow**
   - The repository is designed for static-site publishing through GitHub Actions.
   - `.github/workflows/mkdocs-publish.yml` is the key pipeline for building and deploying the portal; `codeva-publish.yml` appears to support an additional publish path or compliance-oriented deployment process.

9. **Operational boundaries**
   - There is no application runtime, database, or API integration defined in this repo.
   - All “business logic” is effectively in the documentation content and site configuration.

10. **Governance and contribution controls**
   - `.github/CODEOWNERS`, PR templates, and Dependabot config support review discipline and dependency maintenance.
   - `catalog-info.yaml` suggests the repo is also registered in a broader internal developer portal/catalog ecosystem.

11. **Information architecture**
   - The docs are structured as a knowledge portal for two main audiences:
     - **producers** who publish events
     - **consumers** who subscribe and use events
   - Supporting pages handle onboarding, terminology, administrative requirements, and support.

12. **How to diagram it**
   - A clear architecture diagram would show:
     - Authors/editors updating Markdown in `docs/`
     - MkDocs + Material consuming `mkdocs.yml` and assets
     - GitHub Actions building the static site
     - GitHub Pages serving the published portal to end users
   - The diagram should emphasize a **content-to-static-site publishing pipeline** rather than a service-oriented system.

Main entry points: [`mkdocs.yml`](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/mkdocs.yml) (MkDocs config), [`docs/README.md`](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/README.md) (Portal home), [`.github/workflows/mkdocs-publish.yml`](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/workflows/mkdocs-publish.yml) (MkDocs deploy), [`docs/intro-to-eda.md`](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/intro-to-eda.md) (EDA intro)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Documentation content"]
  node_portal_home["Portal home<br/>docs index<br/>[README.md]"]
  node_intro_eda["EDA intro<br/>topic page<br/>[intro-to-eda.md]"]
  node_producer_onboarding["Producer onboarding<br/>topic page"]
  node_produce_events["Produce events<br/>topic page<br/>[produce-events.md]"]
  node_consumer_onboarding["Consumer onboarding<br/>topic page"]
  node_consume_events["Consume events<br/>topic page<br/>[consume-events.md]"]
  node_use_events["Use events<br/>topic page<br/>[use-events.md]"]
  node_environments["Environments<br/>reference page<br/>[environments.md]"]
  node_terminology["Terminology<br/>reference page<br/>[terminology.md]"]
  node_admin_requirements["Admin rules<br/>reference page"]
  node_support["Support<br/>reference page<br/>[get-support.md]"]
  node_offboard["Offboarding<br/>reference page<br/>[offboard.md]"]
  node_media_assets["Images<br/>static assets"]
  node_video_assets["Videos<br/>static assets"]
end

subgraph group_build["Site generation"]
  node_mkdocs_yml["MkDocs config<br/>site config<br/>[mkdocs.yml]"]
  node_requirements["Build deps<br/>python lockfile"]
  node_stylesheets["Styles<br/>presentation assets"]
end

subgraph group_publish["Publishing"]
  node_mkdocs_publish["MkDocs deploy<br/>ci workflow<br/>[mkdocs-publish.yml]"]
  node_codeva_publish["CodeVA deploy<br/>ci workflow<br/>[codeva-publish.yml]"]
  node_github_pages["GitHub Pages<br/>static host"]
end

subgraph group_governance["Governance"]
  node_codeowners["Code owners<br/>repo policy<br/>[CODEOWNERS]"]
  node_dependabot["Dependabot<br/>dependency bot<br/>[dependabot.yml]"]
  node_catalog_info["Catalog entry<br/>catalog metadata<br/>[catalog-info.yaml]"]
end

node_authors(("Authors<br/>editor"))

node_authors -->|"edit"| node_portal_home
node_authors -->|"author"| node_intro_eda
node_authors -->|"author"| node_producer_onboarding
node_authors -->|"author"| node_consumer_onboarding
node_authors -->|"author"| node_support
node_mkdocs_yml -->|"nav"| node_portal_home
node_mkdocs_yml -->|"nav"| node_intro_eda
node_mkdocs_yml -->|"nav"| node_producer_onboarding
node_mkdocs_yml -->|"nav"| node_consumer_onboarding
node_mkdocs_yml -->|"theme"| node_stylesheets
node_mkdocs_yml -->|"assets"| node_media_assets
node_mkdocs_yml -->|"assets"| node_video_assets
node_requirements -->|"build env"| node_mkdocs_publish
node_mkdocs_yml -->|"build input"| node_mkdocs_publish
node_mkdocs_publish -->|"deploy"| node_github_pages
node_codeva_publish -.->|"deploy"| node_github_pages
node_codeowners -->|"review"| node_mkdocs_publish
node_dependabot -->|"update"| node_requirements
node_catalog_info -->|"register"| node_github_pages
node_portal_home -->|"links"| node_intro_eda
node_portal_home -->|"links"| node_produce_events
node_portal_home -->|"links"| node_consume_events
node_portal_home -->|"links"| node_terminology

click node_portal_home "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/README.md"
click node_intro_eda "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/intro-to-eda.md"
click node_producer_onboarding "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/producer-onboarding.md"
click node_produce_events "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/produce-events.md"
click node_consumer_onboarding "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/consumer-onboarding.md"
click node_consume_events "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/consume-events.md"
click node_use_events "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/use-events.md"
click node_environments "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/environments.md"
click node_terminology "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/terminology.md"
click node_admin_requirements "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/administrative-requirements.md"
click node_support "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/get-support.md"
click node_offboard "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/offboard.md"
click node_mkdocs_yml "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/mkdocs.yml"
click node_requirements "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/requirements-lock.txt"
click node_stylesheets "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/tree/main/docs/stylesheets"
click node_media_assets "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/tree/main/docs/img"
click node_video_assets "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/tree/main/docs/videos"
click node_mkdocs_publish "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/workflows/mkdocs-publish.yml"
click node_codeva_publish "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/workflows/codeva-publish.yml"
click node_codeowners "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/CODEOWNERS"
click node_dependabot "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/dependabot.yml"
click node_catalog_info "https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/catalog-info.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_portal_home,node_intro_eda,node_producer_onboarding,node_produce_events,node_consumer_onboarding,node_consume_events,node_use_events,node_environments,node_terminology,node_admin_requirements,node_support,node_offboard,node_media_assets,node_video_assets toneBlue
class node_mkdocs_yml,node_requirements,node_stylesheets toneAmber
class node_mkdocs_publish,node_codeva_publish,node_github_pages toneMint
class node_codeowners,node_dependabot,node_catalog_info toneRose
class node_authors toneNeutral
```

## Components

### Documentation content

Authoritative Markdown topics and supporting media for the portal.

- [Portal home](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/README.md): docs index · Entry point for the documentation site. · `docs/README.md`
- [EDA intro](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/intro-to-eda.md): topic page · Introduction to event-driven architecture. · `docs/intro-to-eda.md`
- [Producer onboarding](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/producer-onboarding.md): topic page · Getting started guidance for event producers. · `docs/producer-onboarding.md`
- [Produce events](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/produce-events.md): topic page · How to publish events into the bus. · `docs/produce-events.md`
- [Consumer onboarding](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/consumer-onboarding.md): topic page · Getting started guidance for event consumers. · `docs/consumer-onboarding.md`
- [Consume events](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/consume-events.md): topic page · How to subscribe to and consume events. · `docs/consume-events.md`
- [Use events](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/use-events.md): topic page · General guidance for using the event bus. · `docs/use-events.md`
- [Environments](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/environments.md): reference page · Environment and deployment context for the portal content. · `docs/environments.md`
- [Terminology](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/terminology.md): reference page · Shared vocabulary for the portal and event bus users. · `docs/terminology.md`
- [Admin rules](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/administrative-requirements.md): reference page · Administrative requirements and controls. · `docs/administrative-requirements.md`
- [Support](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/get-support.md): reference page · Where to get help and request assistance. · `docs/get-support.md`
- [Offboarding](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/docs/offboard.md): reference page · Exit and deprovisioning guidance. · `docs/offboard.md`
- [Images](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/tree/main/docs/img): static assets · Diagrams and images embedded in the portal pages. · `docs/img`
- [Videos](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/tree/main/docs/videos): static assets · Video media used by the documentation pages. · `docs/videos`

### Site generation

MkDocs configuration and local build dependencies.

- [MkDocs config](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/mkdocs.yml): site config · Navigation, theme, and build settings for the documentation site. · `mkdocs.yml`
- [Build deps](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/requirements-lock.txt): python lockfile · Pinned local dependencies for MkDocs development and preview. · `requirements-lock.txt`
- [Styles](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/tree/main/docs/stylesheets): presentation assets · Custom CSS used to augment the Material theme. · `docs/stylesheets`

### Publishing

GitHub Actions workflows that build and deploy the static site.

- [MkDocs deploy](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/workflows/mkdocs-publish.yml): ci workflow · Primary GitHub Actions pipeline for building and publishing the portal. · `.github/workflows/mkdocs-publish.yml`
- [CodeVA deploy](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/workflows/codeva-publish.yml): ci workflow · Secondary publish path for deployment or compliance handling. · `.github/workflows/codeva-publish.yml`
- **GitHub Pages**: static host · Public hosting target for the generated documentation site.

### Governance

Repository controls and catalog metadata.

- [Code owners](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/CODEOWNERS): repo policy · Review ownership and approval rules. · `.github/CODEOWNERS`
- [Dependabot](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/.github/dependabot.yml): dependency bot · Automated dependency update configuration. · `.github/dependabot.yml`
- [Catalog entry](https://github.com/department-of-veterans-affairs/ves-event-bus-developer-portal/blob/main/catalog-info.yaml): catalog metadata · Registration metadata for the broader developer portal catalog. · `catalog-info.yaml`

### Other components

- **Authors**: editor · People maintaining the portal content and configuration.

## Connections

- Authors → Portal home: edit · Authors maintain the portal entry page and navigation surface.
- Authors → EDA intro: author · Authors create and update topic content.
- Authors → Producer onboarding: author · Authors maintain producer onboarding guidance.
- Authors → Consumer onboarding: author · Authors maintain consumer onboarding guidance.
- Authors → Support: author · Authors maintain support and operational pages.
- MkDocs config → Portal home: nav · MkDocs uses the configured navigation to surface the docs site.
- MkDocs config → EDA intro: nav · MkDocs maps source pages into the published site.
- MkDocs config → Producer onboarding: nav · MkDocs maps source pages into the published site.
- MkDocs config → Consumer onboarding: nav · MkDocs maps source pages into the published site.
- MkDocs config → Styles: theme · MkDocs loads custom styling alongside the Material theme.
- MkDocs config → Images: assets · MkDocs serves images as part of the static site.
- MkDocs config → Videos: assets · MkDocs serves video assets as part of the static site.
- Build deps → MkDocs deploy: build env · Pinned dependencies support the CI build and preview environment.
- MkDocs config → MkDocs deploy: build input · The workflow builds the site from the MkDocs configuration and content.
- MkDocs deploy → GitHub Pages: deploy · Primary deployment path publishes the generated static portal.
- CodeVA deploy → GitHub Pages: deploy · Secondary deployment path publishes the generated static portal.
- Code owners → MkDocs deploy: review · Ownership rules help control changes to the publishing pipeline.
- Dependabot → Build deps: update · Dependency automation targets the pinned build environment.
- Catalog entry → GitHub Pages: register · Catalog metadata links the repository to the broader portal ecosystem.
- Portal home → EDA intro: links · The home page connects readers to the main topic pages.
- Portal home → Produce events: links · The home page connects readers to producer guidance.
- Portal home → Consume events: links · The home page connects readers to consumer guidance.
- Portal home → Terminology: links · The home page connects readers to shared terminology.