# mathalama/zovic architecture

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

- Interactive diagram: https://gitdiagram.com/mathalama/zovic
- Repository: https://github.com/mathalama/zovic

## Overview

Zovik is a self-hosted distributed CI/CD system: users configure projects and runners, GitHub pushes can trigger builds, and pipeline steps run in Docker on pull-based agents; users then inspect logs and artifacts. The graph includes the documented DAG, webhook, runner, Docker, artifact, and live-log capabilities. Build orchestration and several advertised capabilities (including encrypted secret storage) are not represented in the supplied tree or sampled implementation, so their wiring is omitted.

Main entry points: [`frontend/src/App.vue`](https://github.com/mathalama/zovic/blob/dev/frontend/src/App.vue) (Web Console), [`server/src/main/java/dev/mathalama/zovik/runner/service/impl/DockerRunnerService.java`](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/service/impl/DockerRunnerService.java) (Docker Executor), [`server/src/main/java/dev/mathalama/zovik/webhook/service/impl/GitHubWebhookService.java`](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/webhook/service/impl/GitHubWebhookService.java) (Webhook Verification), [`frontend/src/api/client.ts`](https://github.com/mathalama/zovic/blob/dev/frontend/src/api/client.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Panel"]
  node_frontend["Web Console<br/>[App.vue]"]
  node_project_ui["Project Pages<br/>[ProjectsPage.vue]"]
  node_runner_ui["Runner Pages<br/>[RunnersPage.vue]"]
  node_api["API Client<br/>[client.ts]"]
end

subgraph group_project["Projects And Triggers"]
  node_project_controller["Project API"]
  node_project_service["Project Service"]
  node_github_integration["GitHub Integration"]
  node_webhook_controller["Webhook API"]
  node_webhook_service["Webhook Verification"]
end

subgraph group_execution["Pipeline Execution"]
  node_pipeline_parser["DAG Parser"]
  node_pipeline_definition["Pipeline Definition"]
  node_runner_api["Runner API"]
  node_runner_pull["Job Pull API"]
  node_job_queue["Job Queue"]
  node_docker_runner["Docker Executor"]
  node_go_agent["Go Agent<br/>[main.go]"]
end

subgraph group_telemetry["Build Results"]
  node_artifact_collector["Artifact Collector"]
  node_artifact_api["Artifact API"]
  node_artifact_store[("Artifact Records")]
  node_log_collector["Log Collector"]
  node_log_stream["Live Log Stream"]
  node_log_api["Log API<br/>[LogController.java]"]
  node_email_notify["Email Notifications"]
end

node_developer(("Developer"))
node_github(("GitHub"))
node_docker[("Docker Engine")]
node_mail(("Mail Service"))

node_developer -->|"uses console"| node_frontend
node_frontend -->|"routes to"| node_project_ui
node_frontend -->|"routes to"| node_runner_ui
node_project_ui -->|"requests"| node_api
node_runner_ui -->|"requests"| node_api
node_api -->|"calls API"| node_project_controller
node_project_controller -->|"delegates"| node_project_service
node_project_service -.->|"integrates"| node_github_integration
node_github -->|"sends push"| node_webhook_controller
node_webhook_controller -->|"processes payload"| node_webhook_service
node_webhook_service -->|"verifies signature"| node_github
node_webhook_service -->|"loads project"| node_project_service
node_pipeline_parser -->|"parses YAML"| node_pipeline_definition
node_go_agent -->|"registers"| node_runner_api
node_go_agent -->|"polls jobs"| node_runner_pull
node_runner_pull -->|"requests job"| node_job_queue
node_docker_runner -->|"dispatches job"| node_job_queue
node_docker_runner -->|"runs containers"| node_docker
node_docker_runner -->|"publishes logs"| node_log_collector
node_log_collector -->|"emits chunks"| node_log_stream
node_log_api -->|"opens stream"| node_log_stream
node_frontend -->|"views logs"| node_log_api
node_artifact_collector -->|"reads patterns"| node_pipeline_parser
node_artifact_collector -->|"saves metadata"| node_artifact_store
node_artifact_api -->|"loads metadata"| node_artifact_store
node_frontend -->|"downloads artifacts"| node_artifact_api
node_email_notify -.->|"sends email"| node_mail

click node_frontend "https://github.com/mathalama/zovic/blob/dev/frontend/src/App.vue"
click node_project_ui "https://github.com/mathalama/zovic/blob/dev/frontend/src/pages/ProjectsPage.vue"
click node_runner_ui "https://github.com/mathalama/zovic/blob/dev/frontend/src/pages/RunnersPage.vue"
click node_api "https://github.com/mathalama/zovic/blob/dev/frontend/src/api/client.ts"
click node_project_controller "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/project/controller/ProjectController.java"
click node_project_service "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/project/service/impl/ProjectServiceImpl.java"
click node_github_integration "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/project/service/impl/GitHubIntegrationService.java"
click node_webhook_controller "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/webhook/controller/WebhookController.java"
click node_webhook_service "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/webhook/service/impl/GitHubWebhookService.java"
click node_pipeline_parser "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/pipeline/service/impl/PipelineServiceImpl.java"
click node_pipeline_definition "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/pipeline/api/dto/PipelineDefinition.java"
click node_runner_api "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/controller/RunnerController.java"
click node_runner_pull "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/controller/RunnerPullController.java"
click node_job_queue "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/service/impl/RunnerJobQueueService.java"
click node_docker_runner "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/service/impl/DockerRunnerService.java"
click node_go_agent "https://github.com/mathalama/zovic/blob/dev/agents/go/main.go"
click node_artifact_collector "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/artifact/service/impl/ArtifactCollectorService.java"
click node_artifact_api "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/artifact/controller/ArtifactController.java"
click node_artifact_store "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/artifact/repository/BuildArtifactRepository.java"
click node_log_collector "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/log/service/impl/LogCollectorService.java"
click node_log_stream "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/log/service/impl/LogStreamingService.java"
click node_log_api "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/log/controller/LogController.java"
click node_email_notify "https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/notification/service/impl/EmailNotificationService.java"

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_frontend,node_project_ui,node_runner_ui,node_api toneBlue
class node_project_controller,node_project_service,node_github_integration,node_webhook_controller,node_webhook_service,node_docker toneAmber
class node_pipeline_parser,node_pipeline_definition,node_runner_api,node_runner_pull,node_job_queue,node_docker_runner,node_go_agent toneMint
class node_artifact_collector,node_artifact_api,node_artifact_store,node_log_collector,node_log_stream,node_log_api,node_email_notify toneRose
class node_developer,node_github,node_mail toneIndigo
```

## Components

### Control Panel

- [Web Console](https://github.com/mathalama/zovic/blob/dev/frontend/src/App.vue): `frontend/src/App.vue`
- [Project Pages](https://github.com/mathalama/zovic/blob/dev/frontend/src/pages/ProjectsPage.vue): `frontend/src/pages/ProjectsPage.vue`
- [Runner Pages](https://github.com/mathalama/zovic/blob/dev/frontend/src/pages/RunnersPage.vue): `frontend/src/pages/RunnersPage.vue`
- [API Client](https://github.com/mathalama/zovic/blob/dev/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Projects And Triggers

- [Project API](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/project/controller/ProjectController.java): `server/src/main/java/dev/mathalama/zovik/project/controller/ProjectController.java`
- [Project Service](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/project/service/impl/ProjectServiceImpl.java): `server/src/main/java/dev/mathalama/zovik/project/service/impl/ProjectServiceImpl.java`
- [GitHub Integration](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/project/service/impl/GitHubIntegrationService.java): `server/src/main/java/dev/mathalama/zovik/project/service/impl/GitHubIntegrationService.java`
- [Webhook API](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/webhook/controller/WebhookController.java): `server/src/main/java/dev/mathalama/zovik/webhook/controller/WebhookController.java`
- [Webhook Verification](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/webhook/service/impl/GitHubWebhookService.java): `server/src/main/java/dev/mathalama/zovik/webhook/service/impl/GitHubWebhookService.java`

### Pipeline Execution

- [DAG Parser](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/pipeline/service/impl/PipelineServiceImpl.java): `server/src/main/java/dev/mathalama/zovik/pipeline/service/impl/PipelineServiceImpl.java`
- [Pipeline Definition](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/pipeline/api/dto/PipelineDefinition.java): `server/src/main/java/dev/mathalama/zovik/pipeline/api/dto/PipelineDefinition.java`
- [Runner API](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/controller/RunnerController.java): `server/src/main/java/dev/mathalama/zovik/runner/controller/RunnerController.java`
- [Job Pull API](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/controller/RunnerPullController.java): `server/src/main/java/dev/mathalama/zovik/runner/controller/RunnerPullController.java`
- [Job Queue](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/service/impl/RunnerJobQueueService.java): `server/src/main/java/dev/mathalama/zovik/runner/service/impl/RunnerJobQueueService.java`
- [Docker Executor](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/runner/service/impl/DockerRunnerService.java): `server/src/main/java/dev/mathalama/zovik/runner/service/impl/DockerRunnerService.java`
- [Go Agent](https://github.com/mathalama/zovic/blob/dev/agents/go/main.go): `agents/go/main.go`

### Build Results

- [Artifact Collector](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/artifact/service/impl/ArtifactCollectorService.java): `server/src/main/java/dev/mathalama/zovik/artifact/service/impl/ArtifactCollectorService.java`
- [Artifact API](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/artifact/controller/ArtifactController.java): `server/src/main/java/dev/mathalama/zovik/artifact/controller/ArtifactController.java`
- [Artifact Records](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/artifact/repository/BuildArtifactRepository.java): `server/src/main/java/dev/mathalama/zovik/artifact/repository/BuildArtifactRepository.java`
- [Log Collector](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/log/service/impl/LogCollectorService.java): `server/src/main/java/dev/mathalama/zovik/log/service/impl/LogCollectorService.java`
- [Live Log Stream](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/log/service/impl/LogStreamingService.java): `server/src/main/java/dev/mathalama/zovik/log/service/impl/LogStreamingService.java`
- [Log API](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/log/controller/LogController.java): `server/src/main/java/dev/mathalama/zovik/log/controller/LogController.java`
- [Email Notifications](https://github.com/mathalama/zovic/blob/dev/server/src/main/java/dev/mathalama/zovik/notification/service/impl/EmailNotificationService.java): `server/src/main/java/dev/mathalama/zovik/notification/service/impl/EmailNotificationService.java`

### Other components

- **Developer**
- **GitHub**
- **Docker Engine**
- **Mail Service**

## Connections

- Developer → Web Console: uses console
- Web Console → Project Pages: routes to
- Web Console → Runner Pages: routes to
- Project Pages → API Client: requests
- Runner Pages → API Client: requests
- API Client → Project API: calls API
- Project API → Project Service: delegates
- Project Service → GitHub Integration: integrates
- GitHub → Webhook API: sends push
- Webhook API → Webhook Verification: processes payload
- Webhook Verification → GitHub: verifies signature
- Webhook Verification → Project Service: loads project
- DAG Parser → Pipeline Definition: parses YAML
- Go Agent → Runner API: registers
- Go Agent → Job Pull API: polls jobs
- Job Pull API → Job Queue: requests job
- Docker Executor → Job Queue: dispatches job
- Docker Executor → Docker Engine: runs containers
- Docker Executor → Log Collector: publishes logs
- Log Collector → Live Log Stream: emits chunks
- Log API → Live Log Stream: opens stream
- Web Console → Log API: views logs
- Artifact Collector → DAG Parser: reads patterns
- Artifact Collector → Artifact Records: saves metadata
- Artifact API → Artifact Records: loads metadata
- Web Console → Artifact API: downloads artifacts
- Email Notifications → Mail Service: sends email