From bb77efce0eeba61b488243bf6684d68fdaff2c7e Mon Sep 17 00:00:00 2001
From: Jiajie Chen <c@jia.je>
Date: Fri, 8 Mar 2024 11:56:44 +0800
Subject: [PATCH] docs: draft new design for buildit v2

---
 DESIGN.md | 42 +++++++++++++++++++++++-------------------
 README.md |  2 +-
 2 files changed, 24 insertions(+), 20 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index 36c2e29..b68b5b2 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1,34 +1,38 @@
-# Buildit
+# BuildIt! 2
+
+## Overview
+
+BuildIt! 2 is the latest generation of BuildIt! build automation system for AOSC OS.
 
 ## Frontend
 
-The current frontend is Telegram bot @aosc_buildit_bot.
+BuildIt! 2 have the following frontends:
+
+1. Web: hosted at https://buildit.aosc.io
+2. Telegram: Telegram bot @aosc_buildit_bot
+3. GitHub: add @aosc-buildit-bot in pr comments
 
-## Backend Server
+## Database
 
-Backend server handles new requests from Frontend. It sends new jobs to message queue.
+BuildIt! 2 uses PostgreSQL as the database.
 
-If the request contains multiple architectures, it is split into multiple ones for each architecture.
+The database should have the following tables:
 
-## Message Queue
+1. pipelines: pipeline is a series of jobs
+2. jobs: job is a specific task for worker to do
+3. packages: track the status of packages in stable branch
 
-Use RabbitMQ:
+The terms `pipelines` and `jobs` are taken from GitLab CI.
 
-```shell
-docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.12-management
-# alternatively
-cd rabbitmq
-docker compose up -d
-```
+## Backend
 
-Queues:
+Backend server handles new requests from Frontend and create new pipeline. The pipeline may contain multi architectures, then it is split into multiple jobs for each architecture.
 
-1. Job submission: job-[arch]
-2. Job completion: job-completion
+Worker can grab new job from backend server. Workers need to send heartbeat to the server periodically reporting its current state, otherwise the job will be rescheduled.
 
-## Worker Server
+## Worker
 
-Worker server fetches jobs from message queue and runs ciel to do the actual build. The result is reported to backend server via message queue.
+Worker server fetches jobs from backend and runs ciel to do the actual build. The result is reported to backend server via HTTP api endpoint.
 
 Each worker can only build for one architecture.
 
@@ -43,4 +47,4 @@ Each job contains the following arguments:
 Job result:
 
 1. List of successful builds
-2. Failed package and link to build log (on paste.aosc.io)
\ No newline at end of file
+2. Failed package and link to build log (on buildit.aosc.io)
\ No newline at end of file
diff --git a/README.md b/README.md
index 6029bf5..c76b6b1 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# AOSC Buildit! Bot
+# AOSC BuildIt! Bot
 
 Build automation with Telegram and GitHub Integrations.