# sefe/dorc architecture

> Architecture diagram of the GitHub repository sefe/dorc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sefe/dorc
- Repository: https://github.com/sefe/dorc

## Overview

DOrc is a deployment orchestration platform: users manage projects, environments, and configuration in the Web UI, then initiate deployments that the API validates and coordinates through deployment requests, build-artifact lookup, and Runner agents. Monitor handles deployment activity and observability; API events provide real-time updates. The API also exposes reference-data, access-control, audit, analytics, and Terraform capabilities. The principal request path is documented in the README; edges for unsampled subsystems are limited to documented relationships rather than inferred calls.

Main entry points: [`src/Dorc.Api/Program.cs`](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Program.cs) (DOrc API), [`src/Dorc.Api/Controllers/RequestController.cs`](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/RequestController.cs) (Deployment requests), [`src/Dorc.Monitor/DeploymentEngine.cs`](https://github.com/sefe/dorc/blob/main/src/Dorc.Monitor/DeploymentEngine.cs) (Deployment monitor), [`src/dorc-web/src/router/routes.ts`](https://github.com/sefe/dorc/blob/main/src/dorc-web/src/router/routes.ts) (Web UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web UI<br/>[routes.ts]"]
end

subgraph group_api["API and management"]
  node_api_entry["DOrc API<br/>[Program.cs]"]
  node_request_api["Deployment requests"]
  node_management_api["Environment and reference data"]
  node_analytics_api["Analytics and audit"]
  node_security["Identity and permissions"]
  node_request_service["Request service<br/>[RequestService.cs]"]
  node_request_models["Request contracts<br/>[CreateRequest.cs]"]
end

subgraph group_execution["Deployment execution"]
  node_request_manager["Request orchestration<br/>[RequestsManager.cs]"]
  node_runner["Runner agent<br/>[Program.cs]"]
  node_monitor["Deployment monitor"]
  node_deployment_events["Deployment events"]
  node_kafka["Kafka event substrate"]
  node_terraform["Terraform support"]
end

subgraph group_data["Persistence and integrations"]
  node_persistent_data[("Persistent data")]
  node_build_adapters["Build providers"]
  node_azure_devops["Azure DevOps client"]
end

node_users(("Users and teams"))
node_azure_service["Azure DevOps"]
node_target_servers(("Target servers"))
node_opensearch["OpenSearch logging"]

node_users -->|"use"| node_web
node_web -->|"REST calls"| node_api_entry
node_web -.->|"subscribe updates"| node_api_entry
node_api_entry -.->|"routes requests"| node_request_api
node_api_entry -.->|"routes management"| node_management_api
node_api_entry -.->|"routes analytics"| node_analytics_api
node_request_api -.->|"delegates"| node_request_service
node_request_api -->|"reads projects"| node_persistent_data
node_request_api -->|"publishes status"| node_deployment_events
node_request_service -.->|"coordinates"| node_request_manager
node_request_manager -->|"reads project data"| node_persistent_data
node_request_manager -->|"selects provider"| node_build_adapters
node_build_adapters -.->|"uses client"| node_azure_devops
node_azure_devops -->|"fetches artifacts"| node_azure_service
node_api_entry -->|"reads and writes"| node_persistent_data
node_api_entry -->|"authenticates requests"| node_security
node_api_entry -->|"sends job instructions"| node_runner
node_runner -->|"reports status"| node_api_entry
node_runner -->|"executes scripts"| node_target_servers
node_api_entry -.->|"publishes updates"| node_deployment_events
node_deployment_events -.->|"sends deployment events"| node_monitor
node_monitor -->|"pushes logs"| node_opensearch
node_monitor -.->|"subscribes events"| node_api_entry
node_monitor -.->|"signals request polling"| node_kafka
node_api_entry -.->|"serves Terraform API"| node_terraform
node_request_api -->|"accepts request data"| node_request_models

click node_web "https://github.com/sefe/dorc/blob/main/src/dorc-web/src/router/routes.ts"
click node_api_entry "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Program.cs"
click node_request_api "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/RequestController.cs"
click node_management_api "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/RefDataEnvironmentsController.cs"
click node_analytics_api "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/AnalyticsController.cs"
click node_security "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Security/ClaimsPrincipalReaderFactory.cs"
click node_request_service "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Services/RequestService.cs"
click node_request_manager "https://github.com/sefe/dorc/blob/main/src/Dorc.Core/RequestsManager.cs"
click node_request_models "https://github.com/sefe/dorc/blob/main/src/Dorc.ApiModel/CreateRequest.cs"
click node_persistent_data "https://github.com/sefe/dorc/blob/main/src/Dorc.PersistentData/Sources/Interfaces/IEnvironmentsPersistentSource.cs"
click node_build_adapters "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Services/DeployableBuildFactory.cs"
click node_azure_devops "https://github.com/sefe/dorc/blob/main/src/Dorc.AzureDevOps.Client/AzureDevOpsApiClientFactory.cs"
click node_runner "https://github.com/sefe/dorc/blob/main/src/Dorc.Runner/Program.cs"
click node_monitor "https://github.com/sefe/dorc/blob/main/src/Dorc.Monitor/DeploymentEngine.cs"
click node_deployment_events "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Events/DirectDeploymentEventPublisher.cs"
click node_kafka "https://github.com/sefe/dorc/blob/main/src/Dorc.Kafka.Events/DependencyInjection/KafkaResultsStatusSubstrateServiceCollectionExtensions.cs"
click node_terraform "https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/TerraformController.cs"

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_web,node_users toneBlue
class node_api_entry,node_request_api,node_management_api,node_analytics_api,node_security,node_request_service,node_request_models toneAmber
class node_request_manager,node_runner,node_monitor,node_deployment_events,node_kafka,node_terraform,node_target_servers toneMint
class node_persistent_data,node_build_adapters,node_azure_devops toneRose
class node_azure_service,node_opensearch toneIndigo
```

## Components

### User experience

- [Web UI](https://github.com/sefe/dorc/blob/main/src/dorc-web/src/router/routes.ts): `src/dorc-web/src/router/routes.ts`

### API and management

- [DOrc API](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Program.cs): `src/Dorc.Api/Program.cs`
- [Deployment requests](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/RequestController.cs): `src/Dorc.Api/Controllers/RequestController.cs`
- [Environment and reference data](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/RefDataEnvironmentsController.cs): `src/Dorc.Api/Controllers/RefDataEnvironmentsController.cs`
- [Analytics and audit](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/AnalyticsController.cs): `src/Dorc.Api/Controllers/AnalyticsController.cs`
- [Identity and permissions](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Security/ClaimsPrincipalReaderFactory.cs): `src/Dorc.Api/Security/ClaimsPrincipalReaderFactory.cs`
- [Request service](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Services/RequestService.cs): `src/Dorc.Api/Services/RequestService.cs`
- [Request contracts](https://github.com/sefe/dorc/blob/main/src/Dorc.ApiModel/CreateRequest.cs): `src/Dorc.ApiModel/CreateRequest.cs`

### Deployment execution

- [Request orchestration](https://github.com/sefe/dorc/blob/main/src/Dorc.Core/RequestsManager.cs): `src/Dorc.Core/RequestsManager.cs`
- [Runner agent](https://github.com/sefe/dorc/blob/main/src/Dorc.Runner/Program.cs): `src/Dorc.Runner/Program.cs`
- [Deployment monitor](https://github.com/sefe/dorc/blob/main/src/Dorc.Monitor/DeploymentEngine.cs): `src/Dorc.Monitor/DeploymentEngine.cs`
- [Deployment events](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Events/DirectDeploymentEventPublisher.cs): `src/Dorc.Api/Events/DirectDeploymentEventPublisher.cs`
- [Kafka event substrate](https://github.com/sefe/dorc/blob/main/src/Dorc.Kafka.Events/DependencyInjection/KafkaResultsStatusSubstrateServiceCollectionExtensions.cs): `src/Dorc.Kafka.Events/DependencyInjection/KafkaResultsStatusSubstrateServiceCollectionExtensions.cs`
- [Terraform support](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Controllers/TerraformController.cs): `src/Dorc.Api/Controllers/TerraformController.cs`

### Persistence and integrations

- [Persistent data](https://github.com/sefe/dorc/blob/main/src/Dorc.PersistentData/Sources/Interfaces/IEnvironmentsPersistentSource.cs): `src/Dorc.PersistentData/Sources/Interfaces/IEnvironmentsPersistentSource.cs`
- [Build providers](https://github.com/sefe/dorc/blob/main/src/Dorc.Api/Services/DeployableBuildFactory.cs): `src/Dorc.Api/Services/DeployableBuildFactory.cs`
- [Azure DevOps client](https://github.com/sefe/dorc/blob/main/src/Dorc.AzureDevOps.Client/AzureDevOpsApiClientFactory.cs): `src/Dorc.AzureDevOps.Client/AzureDevOpsApiClientFactory.cs`

### Other components

- **Users and teams**
- **Azure DevOps**
- **Target servers**
- **OpenSearch logging**

## Connections

- Users and teams → Web UI: use (evidence: `README.md`)
- Web UI → DOrc API: REST calls (evidence: `README.md`)
- Web UI → DOrc API: subscribe updates (evidence: `README.md`)
- DOrc API → Deployment requests: routes requests
- DOrc API → Environment and reference data: routes management
- DOrc API → Analytics and audit: routes analytics
- Deployment requests → Request service: delegates
- Deployment requests → Persistent data: reads projects (evidence: `src/Dorc.Api/Controllers/RequestController.cs`)
- Deployment requests → Deployment events: publishes status (evidence: `src/Dorc.Api/Controllers/RequestController.cs`)
- Request service → Request orchestration: coordinates
- Request orchestration → Persistent data: reads project data (evidence: `src/Dorc.Core/RequestsManager.cs`)
- Request orchestration → Build providers: selects provider (evidence: `src/Dorc.Core/RequestsManager.cs`)
- Build providers → Azure DevOps client: uses client
- Azure DevOps client → Azure DevOps: fetches artifacts (evidence: `README.md`)
- DOrc API → Persistent data: reads and writes (evidence: `README.md`)
- DOrc API → Identity and permissions: authenticates requests (evidence: `README.md`)
- DOrc API → Runner agent: sends job instructions (evidence: `README.md`)
- Runner agent → DOrc API: reports status (evidence: `README.md`)
- Runner agent → Target servers: executes scripts (evidence: `README.md`)
- DOrc API → Deployment events: publishes updates (evidence: `README.md`)
- Deployment events → Deployment monitor: sends deployment events (evidence: `README.md`)
- Deployment monitor → OpenSearch logging: pushes logs (evidence: `README.md`)
- Deployment monitor → DOrc API: subscribes events (evidence: `README.md`)
- Deployment monitor → Kafka event substrate: signals request polling
- DOrc API → Terraform support: serves Terraform API
- Deployment requests → Request contracts: accepts request data (evidence: `src/Dorc.Api/Controllers/RequestController.cs`)
