From 74607ec084d7ddd97b382495ad36e61e4e3fc9c4 Mon Sep 17 00:00:00 2001 From: alex289 Date: Thu, 23 Apr 2026 21:50:20 +0200 Subject: [PATCH 1/4] feat: Add initial architecture docs Co-authored-by: Copilot --- content/docs/architecture.mdx | 43 +++++++++++++++++++++++++++++++++++ content/docs/meta.json | 1 + src/routes/docs/$.tsx | 7 +++++- 3 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 content/docs/architecture.mdx diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx new file mode 100644 index 0000000..21eb2f2 --- /dev/null +++ b/content/docs/architecture.mdx @@ -0,0 +1,43 @@ +--- +title: Architecture +description: An overview of the architecture of OrcaCD. +--- + +## Agent-Hub Architecture + +OrcaCD follows a Hub-Agent architecture, where the Hub is the central control plane that manages the state of the system and the Agents are responsible for executing deployments and reporting back to the Hub. +This architecture allows for a scalable and flexible deployment system that can be easily extended with new features and integrations. + +### Hub + +The Hub is the central component of OrcaCD that manages the state of the system, processes deployment instructions, and provides an API for the Agents and other clients to interact with the system. +Additionally, the Hub serves the web UI and provides a REST API for external integrations. It is responsible for processing deployment instructions, managing the state of the system, and providing an interface for the Agents to communicate with. + +### Agent + +The Agent is responsible for executing deployments and reporting back to the Hub. +It runs on the target environment where the applications are deployed and communicates with the Hub to receive deployment instructions and send status updates. + +## GitOps Model + +GitOps is a set of practices that uses Git as the single source of truth for declarative infrastructure and applications. +OrcaCD follows the GitOps model, where the desired state of the system is defined in Git and the Hub continuously reconciles the actual state with the desired state. + +### Git Syncing + +OrcaCD supports multiple Git syncing strategies, including polling and webhooks, to keep the Hub in sync with the desired state defined in Git. +This allows for a seamless integration with existing Git workflows and tools. + +## Server-Sent-Events (SSE) + +In order to provide real-time updates to the UI and other clients, OrcaCD uses Server-Sent-Events (SSE) to stream events from the Hub to the clients. +This allows for a responsive and interactive user experience, as clients can receive updates about the state of deployments, agents, and other system components in real-time without the need for polling. + +## Persistence + +For persistence, OrcaCD uses a sqlite database to store the state of the system. +The database is being accessed through the Hub, which provides an API for the Agents and other clients to interact with the database. + +### Encryption + +To ensure the security of sensitive data, OrcaCD supports encryption of string data in the database. diff --git a/content/docs/meta.json b/content/docs/meta.json index cbc86d6..6d9ba31 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -6,6 +6,7 @@ "---Getting Started---", "index", "demo", + "architecture", "---[Rocket]Setup---", "...setup", "---[Settings]Configuration---", diff --git a/src/routes/docs/$.tsx b/src/routes/docs/$.tsx index 672766a..9d24fac 100644 --- a/src/routes/docs/$.tsx +++ b/src/routes/docs/$.tsx @@ -58,7 +58,12 @@ const clientLoader = browserCollections.docs.createClientLoader({ }, ) { return ( - + {frontmatter.title} {frontmatter.description}
From 5545acdf1a0f6fd957b8d46d90c7a099437c322c Mon Sep 17 00:00:00 2001 From: alex289 Date: Thu, 23 Apr 2026 22:54:31 +0200 Subject: [PATCH 2/4] feat: Apply review suggestions Co-authored-by: Copilot --- content/docs/architecture.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index 21eb2f2..619eb3a 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -18,6 +18,12 @@ Additionally, the Hub serves the web UI and provides a REST API for external int The Agent is responsible for executing deployments and reporting back to the Hub. It runs on the target environment where the applications are deployed and communicates with the Hub to receive deployment instructions and send status updates. +### Communication + +The communication between the Hub and the Agents is using protocol buffers (protobuf) for efficient serialization and websockets for bidirectional communication. +This allows for a responsive and efficient communication channel between the Hub and the Agents, enabling real-time updates and interactions. +To make the communication secure, OrcaCD encrypts the data using post-quantum AEGIS-256.This also prevents messages from being read behind a proxy which does TLS termination or uses old / weak TLS configuration. + ## GitOps Model GitOps is a set of practices that uses Git as the single source of truth for declarative infrastructure and applications. @@ -30,7 +36,7 @@ This allows for a seamless integration with existing Git workflows and tools. ## Server-Sent-Events (SSE) -In order to provide real-time updates to the UI and other clients, OrcaCD uses Server-Sent-Events (SSE) to stream events from the Hub to the clients. +In order to provide real-time updates to the UI and other clients, OrcaCD uses Server-Sent-Events (SSE) to stream events from the Hub to the web ui. This allows for a responsive and interactive user experience, as clients can receive updates about the state of deployments, agents, and other system components in real-time without the need for polling. ## Persistence @@ -40,4 +46,4 @@ The database is being accessed through the Hub, which provides an API for the Ag ### Encryption -To ensure the security of sensitive data, OrcaCD supports encryption of string data in the database. +To ensure the security of sensitive data, all string data in the database is encrypted. From 282a140c3fdc0b7daa8d899ec96ed73d92050ca7 Mon Sep 17 00:00:00 2001 From: Alex Date: Fri, 24 Apr 2026 09:35:52 +0200 Subject: [PATCH 3/4] Update architecture.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Timo Kössler --- content/docs/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index 619eb3a..0cd9351 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -22,7 +22,7 @@ It runs on the target environment where the applications are deployed and commun The communication between the Hub and the Agents is using protocol buffers (protobuf) for efficient serialization and websockets for bidirectional communication. This allows for a responsive and efficient communication channel between the Hub and the Agents, enabling real-time updates and interactions. -To make the communication secure, OrcaCD encrypts the data using post-quantum AEGIS-256.This also prevents messages from being read behind a proxy which does TLS termination or uses old / weak TLS configuration. +To make the communication secure, OrcaCD uses AEGIS-256 encryption and a post-quantum key exchange to encrypt the data. This also prevents messages from being read behind a proxy which does TLS termination or uses old / weak TLS configuration. ## GitOps Model From d5b63f017c373e73b95b0cf296c9e726e74ff2f1 Mon Sep 17 00:00:00 2001 From: Alex Date: Fri, 24 Apr 2026 09:36:01 +0200 Subject: [PATCH 4/4] Update architecture.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Timo Kössler --- content/docs/architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index 0cd9351..44831cc 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -46,4 +46,4 @@ The database is being accessed through the Hub, which provides an API for the Ag ### Encryption -To ensure the security of sensitive data, all string data in the database is encrypted. +To ensure the security of sensitive data, all sensitive string data in the database is encrypted.