High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The CircleCI Docs Static Site is a documentation platform constructed using Antora, a multi-repository static site generator. The architecture is designed to manage complex, multi-component technical documentation by separating content (written in AsciiDoc) from presentation (handled by a custom UI bundle). The system also integrates external API documentation and custom extensions to enhance core site functionality.
Sources: ARCHITECTURE.md:10-18, README.md:13-18
Core System Components
The project is structured into five primary architectural blocks that manage content, user interface, build orchestration, and external integrations.
| Component | Responsibility | Location |
|---|---|---|
| Documentation Content | Source files for guides, references, and server administration. | docs/ |
| UI Bundle | The theme, templates, and styles for the frontend. | ui/ |
| Build System | Gulp-based tasks for site assembly and local development. | gulp.d/ |
| Extensions | Custom logic for metadata, content export, and AsciiDoc processing. | extensions/ |
| Utility Scripts | Scripts for maintenance, migration, and metadata generation. | scripts/ |
Sources: ARCHITECTURE.md:25-45, TECHNICAL_REFERENCE.md:111-125
Content Organization
Documentation is divided into logical components, each containing its own antora.yml configuration and a standard directory structure for pages, partials, and assets.
The diagram above illustrates the standard directory structure required for Antora to process a documentation component.
Sources: ARCHITECTURE.md:49-65, CONTENT_AUTHORING.md:23-40
Build Pipeline and Data Flow
The build pipeline is a multi-stage process orchestrated by Gulp. It combines static content with dynamic UI assets and external API specifications.
Site Assembly Process
The pipeline follows a sequential flow to ensure all dependencies (UI and API docs) are prepared before the final site generation.
The flowchart shows the sequential stages of the documentation build pipeline, starting from UI preparation to final assembly.
Sources: ARCHITECTURE.md:83-101, TECHNICAL_REFERENCE.md:129-145
API Documentation Integration
The project integrates two distinct versions of API documentation into the static site. API v1 is treated as static content, while API v2 is fetched live and processed through a sophisticated pipeline using Redocly.
This sequence diagram details the differentiated processing paths for static v1 docs versus the live-fetched and patched v2 documentation.
Sources: gulp.d/tasks/build-api-docs.js:46-150, API_DOCS_INTEGRATION.md:9-25
CircleCI Server Architecture Integration
The documentation site specifically handles the complex architecture of CircleCI Server v4.1, which operates within a Kubernetes cluster (EKS or GKE). The application architecture involves several critical external services and a Nomad-based execution environment.
Service Port Map
CircleCI Server exposes specific services through a single load balancer using various ports for frontend, execution control, and internal processing.
| Service | Port | Description |
|---|---|---|
| Frontend/API | 80/443 | Exposes the web application to end users. |
| Nomad Control Plane | 4647 | Exposes RPC protocol for Nomad clients. |
| Output Processor | 8585 | Ingests output from runners (gRPC). |
| VM Service | 3000 | Provisions virtual machines for jobs. |
Sources: archive/server 4.1/server-admin/modules/overview/pages/circleci-server-overview.adoc:14-38
Execution Topology
CircleCI Server separates the control plane (within Kubernetes) from the execution plane (Nomad clients).
The diagram shows the relationship between the Kubernetes control plane and external Nomad clients/Object Storage.
Sources: archive/server 4.1/server-admin/modules/overview/pages/circleci-server-overview.adoc:61-75
UI and Extension Framework
The UI is built on a custom theme utilizing the Tailwind CSS framework and Handlebars templates. It interacts with Antora through the following mechanisms:
- Templates:
layouts/default.hbsdefines the global structure, while partials likeheader.hbsmanage shared components. - Extensions: Custom JavaScript files in
extensions/hook into Antora's lifecycle to add page metadata (likelast_updateddates) or export content for search indexing (Algolia). - Navigation: Defined in
nav.adocfiles, which Antora uses to build the hierarchical sidebar rendered viapartials/nav.hbs.
Sources: ARCHITECTURE.md:104-121, TECHNICAL_REFERENCE.md:152-185
Conclusion
The CircleCI Docs Static Site architecture provides a robust environment for technical content delivery by decoupling the build logic from content authoring. By leveraging Antora for versioned component management, Gulp for automated pipeline orchestration, and custom Redocly integrations for live API documentation, the system maintains a unified and high-performance documentation platform.
Sources: ARCHITECTURE.md:17-21, README.md:13-18