How department-of-veterans-affairs/ves-event-bus-developer-portal works
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 MkDocs config · README.md Portal home · mkdocs-publish.yml MkDocs deploy · intro-to-eda.md EDA intro
Components 24
Documentation content
Authoritative Markdown topics and supporting media for the portal.
- Portal home · Entry point for the documentation site.
docs/README.md - EDA intro · Introduction to event-driven architecture.
docs/intro-to-eda.md - Producer onboarding · Getting started guidance for event producers.
docs/producer-onboarding.md - Produce events · How to publish events into the bus.
docs/produce-events.md - Consumer onboarding · Getting started guidance for event consumers.
docs/consumer-onboarding.md - Consume events · How to subscribe to and consume events.
docs/consume-events.md - Use events · General guidance for using the event bus.
docs/use-events.md - Environments · Environment and deployment context for the portal content.
docs/environments.md - Terminology · Shared vocabulary for the portal and event bus users.
docs/terminology.md - Admin rules · Administrative requirements and controls.
docs/administrative-requirements.md - Support · Where to get help and request assistance.
docs/get-support.md - Offboarding · Exit and deprovisioning guidance.
docs/offboard.md - Images · Diagrams and images embedded in the portal pages.
docs/img - Videos · Video media used by the documentation pages.
docs/videos
Site generation
MkDocs configuration and local build dependencies.
- MkDocs config · Navigation, theme, and build settings for the documentation site.
mkdocs.yml - Build deps · Pinned local dependencies for MkDocs development and preview.
requirements-lock.txt - Styles · Custom CSS used to augment the Material theme.
docs/stylesheets
Publishing
GitHub Actions workflows that build and deploy the static site.
- MkDocs deploy · Primary GitHub Actions pipeline for building and publishing the portal.
.github/workflows/mkdocs-publish.yml - CodeVA deploy · Secondary publish path for deployment or compliance handling.
.github/workflows/codeva-publish.yml - GitHub Pages · Public hosting target for the generated documentation site.
Governance
Repository controls and catalog metadata.
- Code owners · Review ownership and approval rules.
.github/CODEOWNERS - Dependabot · Automated dependency update configuration.
.github/dependabot.yml - Catalog entry · Registration metadata for the broader developer portal catalog.
catalog-info.yaml
Other components
- Authors · People maintaining the portal content and configuration.
Connections 23
- 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.