diff --git a/docs/docs/92-development/05-architecture.md b/docs/docs/92-development/05-architecture.md index b5ac422e6..556c595c9 100644 --- a/docs/docs/92-development/05-architecture.md +++ b/docs/docs/92-development/05-architecture.md @@ -1,8 +1,16 @@ # Architecture -## Package architecture +## Module Interactions -![Woodpecker architecture](./woodpecker-architecture.png) +![Woodpecker architecture](./woodpecker-architecture.svg) + + ## System architecture diff --git a/docs/docs/92-development/woodpecker-architecture.dot b/docs/docs/92-development/woodpecker-architecture.dot new file mode 100644 index 000000000..e72bede01 --- /dev/null +++ b/docs/docs/92-development/woodpecker-architecture.dot @@ -0,0 +1,157 @@ +digraph WoodpeckerArchitecture { + graph [ + rankdir=TB, + splines=ortho, + nodesep=0.5, + ranksep=0.8, + fontname="Helvetica" + ] + + node [ + shape=box, + style="rounded,filled", + fillcolor="#2b2b2b", + fontcolor="white", + fontname="Helvetica" + ] + + edge [ + color="#bdbdbd", + arrowsize=0.7 + ] + + /* ===================== UI ===================== */ + subgraph cluster_ui { + label="UI" + fillcolor="#c7efe9" + fontcolor="black" + style="rounded,filled" + + ui_web [label="web/"] + } + + /* ===================== SDK ===================== */ + subgraph cluster_sdk { + label="SDK (woodpecker-go)" + fillcolor="#e8f5e9" + fontcolor="black" + style="rounded,filled" + + sdk [label="woodpecker-go"] + } + + /* ===================== CLI ===================== */ + subgraph cluster_cli { + label="woodpecker-cli" + fillcolor="#bfe9e0" + fontcolor="black" + style="rounded,filled" + + cli_cmd [label="cmd/cli/"] + cli_core [label="cli/"] + } + + /* ===================== Agent ===================== */ + subgraph cluster_agent { + label="woodpecker-agent" + fillcolor="#ffe0c7" + fontcolor="black" + style="rounded,filled" + + agent_cmd [label="cmd/agent/"] + agent_core [label="agent/"] + } + + /* ===================== Pipelines ===================== */ + subgraph cluster_pipelines { + label="Pipelines" + fillcolor="#ffe8d6" + fontcolor="black" + style="rounded,filled" + + pipe_core [label="pipeline/"] + pipe_frontend [label="pipeline/frontend/\n(yaml)"] + pipe_backend [label="pipeline/backend/\n(exec engines)"] + } + + /* ===================== Server ===================== */ + subgraph cluster_server { + label="woodpecker-server" + fillcolor="#dbe9ff" + fontcolor="black" + style="rounded,filled" + + srv_cmd [label="cmd/server/"] + srv_router [label="server/router/"] + srv_api [label="server/api/"] + srv_grpc [label="server/rpc/"] + srv_queue [label="server/queue/"] + srv_pubsub [label="server/pubsub/"] + srv_store [label="server/store/"] + srv_model [label="server/model/"] + srv_forge [label="server/forge/"] + } + + /* ===================== Shared Libs ===================== */ + subgraph cluster_shared { + label="Shared Libs" + fillcolor="#eeeeee" + fontcolor="black" + style="rounded,filled" + + shared_util [label="shared/util/"] + shared_token [label="shared/token/"] + shared_http [label="shared/httputil/"] + shared_log [label="shared/logger/"] + } + + /* ===================== External ===================== */ + subgraph cluster_external { + label="External Systems" + style="rounded,dashed" + fontcolor="white" + + ext_scm [label="SCM Providers", shape=cloud] + ext_db [label="Database", shape=cylinder] + } + + /* ===================== Runtime Interactions ===================== */ + + /* UI */ + ui_web -> srv_router [xlabel="HTTP"] + ui_web -> srv_api [xlabel="REST API"] + + /* CLI */ + cli_cmd -> cli_core + cli_core -> sdk + sdk -> srv_api [xlabel="REST API"] + + /* Agent */ + agent_cmd -> agent_core + agent_core -> srv_grpc [xlabel="gRPC connect"] + agent_core -> srv_queue [xlabel="poll work"] + agent_core -> pipe_backend [xlabel="execute steps"] + + /* Pipelines */ + pipe_frontend -> pipe_core + pipe_core -> pipe_backend + + /* Server internal flow */ + srv_cmd -> srv_router + srv_router -> srv_api + srv_api -> srv_store + srv_api -> srv_pubsub + srv_api -> srv_queue + srv_grpc -> srv_queue + srv_store -> srv_model + + /* External integrations */ + srv_forge -> ext_scm [xlabel="SCM API"] + srv_store -> ext_db [xlabel="SQL"] + + /* Shared libs usage (consumer -> library) */ + srv_router -> shared_token + srv_api -> shared_http + srv_grpc -> shared_log + pipe_core -> shared_util +} diff --git a/docs/docs/92-development/woodpecker-architecture.png b/docs/docs/92-development/woodpecker-architecture.png deleted file mode 100644 index 22f6a054a..000000000 Binary files a/docs/docs/92-development/woodpecker-architecture.png and /dev/null differ diff --git a/docs/docs/92-development/woodpecker-architecture.svg b/docs/docs/92-development/woodpecker-architecture.svg new file mode 100644 index 000000000..5bb308a59 --- /dev/null +++ b/docs/docs/92-development/woodpecker-architecture.svg @@ -0,0 +1,352 @@ + + + + + + +WoodpeckerArchitecture + + +cluster_ui + +UI + + +cluster_sdk + +SDK (woodpecker-go) + + +cluster_cli + +woodpecker-cli + + +cluster_agent + +woodpecker-agent + + +cluster_pipelines + +Pipelines + + +cluster_server + +woodpecker-server + + +cluster_shared + +Shared Libs + + +cluster_external + +External Systems + + + +ui_web + +web/ + + + +srv_router + +server/router/ + + + +ui_web->srv_router + + +HTTP + + + +srv_api + +server/api/ + + + +ui_web->srv_api + + +REST API + + + +sdk + +woodpecker-go + + + +sdk->srv_api + + +REST API + + + +cli_cmd + +cmd/cli/ + + + +cli_core + +cli/ + + + +cli_cmd->cli_core + + + + + +cli_core->sdk + + + + + +agent_cmd + +cmd/agent/ + + + +agent_core + +agent/ + + + +agent_cmd->agent_core + + + + + +pipe_backend + +pipeline/backend/ +(exec engines) + + + +agent_core->pipe_backend + + +execute steps + + + +srv_grpc + +server/rpc/ + + + +agent_core->srv_grpc + + +gRPC connect + + + +srv_queue + +server/queue/ + + + +agent_core->srv_queue + + +poll work + + + +pipe_core + +pipeline/ + + + +pipe_core->pipe_backend + + + + + +shared_util + +shared/util/ + + + +pipe_core->shared_util + + + + + +pipe_frontend + +pipeline/frontend/ +(yaml) + + + +pipe_frontend->pipe_core + + + + + +srv_cmd + +cmd/server/ + + + +srv_cmd->srv_router + + + + + +srv_router->srv_api + + + + + +shared_token + +shared/token/ + + + +srv_router->shared_token + + + + + +srv_api->srv_queue + + + + + +srv_pubsub + +server/pubsub/ + + + +srv_api->srv_pubsub + + + + + +srv_store + +server/store/ + + + +srv_api->srv_store + + + + + +shared_http + +shared/httputil/ + + + +srv_api->shared_http + + + + + +srv_grpc->srv_queue + + + + + +shared_log + +shared/logger/ + + + +srv_grpc->shared_log + + + + + +srv_model + +server/model/ + + + +srv_store->srv_model + + + + + +ext_db + + +Database + + + +srv_store->ext_db + + +SQL + + + +srv_forge + +server/forge/ + + + +ext_scm + +SCM Providers + + + +srv_forge->ext_scm + + +SCM API + + + diff --git a/flake.nix b/flake.nix index 1e7df0045..543d8e534 100644 --- a/flake.nix +++ b/flake.nix @@ -45,6 +45,9 @@ protoc-gen-go protoc-gen-go-grpc gcc + + # docs + graphviz ]; CFLAGS = "-I${pkgs.glibc.dev}/include"; LDFLAGS = "-L${pkgs.glibc}/lib";