Documentation on gobrave - Bioinformatics Analysis Platform

Quick Start

Wed, 12 Aug 2026 00:00:00 +0800

Overview

This guide helps you boot gobrave locally in minutes, using the default Go server entrypoint.

Prerequisites

Go 1.25 or newer
A reachable database: SQLite (default), MySQL, or PostgreSQL
Docker, k8s, or k3s if you want containerized analysis runtime

1. Clone And Enter Project

1
2


git clone https://github.com/gobravedev/gobrave.git
cd gobrave

2. Create Runtime Config

1

cp config.example.yml config.yml

Edit at least:

Configuration

Wed, 12 Aug 2026 00:00:00 +0800

Overview

gobrave loads configuration from defaults, then merges values from config.yml, and finally applies CLI overrides.

Resolution Order

Configuration priority is:

Built-in defaults
config.yml
CLI flags (--port, --db-driver, --runtime, etc.)

Config File Location

At startup, config path is resolved in this order:

--config CLI flag
external path resolution for config.yml

Core Sections

`server`

1
2
3
4


server:
 host: 0.0.0.0
 port: 8082
 log_path: logs/server.log

`database`

1
2
3
4
5
6
7
8
9


database:
 driver: sqlite # sqlite | mysql | postgres
 host: 127.0.0.1
 port: "5432"
 user: postgres
 password: ""
 name: postgres
 ssl_mode: disable
 path: "" # used by sqlite

`container`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


container:
 runtime: docker # docker | k8s | k3s
 kubernetes:
 namespace: default
 kubeconfig: ""
 in_cluster: false
 refresh_image_status_on_start: true
 recover_running_dag_on_start: true
 cleanup_dag_node_containers_before_start: true
 delete_container_on_node_success: true
 dag_node_cleanup_on_failed: stop
 dag_node_cleanup_on_dag_finished: delete
 create_queue_max_concurrency: 3
 create_queue_max_pending: 50

`route`

route.registry controls route registration strategy:

Architecture

Wed, 12 Aug 2026 00:00:00 +0800

Overview

gobrave is a modular Go backend centered around project-scoped bioinformatics workflows, data assets, and containerized execution.

High-Level Components

flowchart TD
 UI[Web / API Clients] --> API[GIN Router + Handlers]
 API --> APP[Application Services]
 APP --> DOM[Domain Managers]
 DOM --> RT[Container Runtime Registry]
 DOM --> REPO[Repository Layer]
 REPO --> DB[(MySQL/Postgres/SQLite)]

 APP --> BUS[In-Memory Event Bus]
 BUS --> WK[Outbox Dispatcher + Workers]
 WK --> RT

Runtime Composition

At startup, gobrave builds a dependency container and wires:

Container Management

Wed, 12 Aug 2026 00:00:00 +0800

Overview

gobrave uses a unified container management model for interactive apps and workflow runtime tasks.

Runtime Backends

Configured by container.runtime:

docker
k8s
k3s

Runtime resolution is centralized in the container runtime registry.

Main Entities

Container image: image metadata and pull policy
Container template: reusable launch definition
App session: user-facing running environment based on template
Container instance: runtime lifecycle state record
Outbox event: durable async lifecycle request

Core API Groups

Image And Template

/container/image/*
/container/template/*

App Session Lifecycle

/container/app-session/create
/container/app-session/start
/container/app-session/stop
/container/app-session/delete

Runtime Monitoring

/container/runtime/monitoring/list
/container/queue/status
/container/outbox/list-by-page

Lifecycle Model

Typical flow:

Data Management

Wed, 12 Aug 2026 00:00:00 +0800

Overview

The gobrave data model is project-centric and designed for reproducible workflow input assembly.

Core Data Objects

Dataset: logical collection of biological assets
Sample: biological sample metadata record
File: physical or logical file metadata
Relations:
project <-> dataset
dataset <-> sample
dataset <-> file
sample <-> file

API Surface

Data endpoints are exposed under /api/v1 and grouped as:

/data/dataset/*
/data/project-dataset/*
/data/file/*
/data/sample/*
/data/dataset-file/*
/data/sample-file/*
/data/dataset-sample/*

Typical Data Workflow

Create project.
Create datasets.
Register samples and files.
Bind sample/file roles (for example FASTQ_R1, FASTQ_R2).
Link assets into dataset relationships.
Build workflow input selectors from these relations.

Workflow Integration

The workflow engine can resolve structured inputs from managed data:

Container Queue Monitoring

Tue, 11 Aug 2026 00:00:00 +0800

Overview

This document explains how gobrave exposes container create-queue health, how to interpret each metric, and how the queue status is computed internally.

The monitoring endpoint is designed for operators and UI polling clients that need to answer:

Is queue mode enabled?
How many create slots are currently occupied?
How many create requests are waiting?
What are the configured hard limits?

Architecture

flowchart LR
 subgraph Client[Client Layer]
 UI[Web UI / Ops Script];
 end;

 subgraph API[API Layer]
 H[ContainerHandler.GetQueueStatus];
 end;

 subgraph Worker[Queue Layer]
 W[ContainerCreateWorker];
 QS[QueueStatus];
 end;

 subgraph Data[Data Layer]
 DB[(ContainerInstance + OutboxEvent)];
 end;

 UI -->|GET /container/queue/status| H;
 H -->|QueueStatus call| W;
 W --> QS;
 QS -->|CountContainerInstanceByStatuses| DB;
 QS -->|CountPendingOutboxEventsByType ContainerCreateRequest| DB;
 H -->|JSON response| UI;

Boot-Time Wiring for Fault Tolerance and Accuracy

The queue-monitoring path relies on explicit startup wiring in the dependency container. This wiring is what makes queue status resilient and restart-safe, not just observable.

Container Worker Queue System

Tue, 11 Aug 2026 00:00:00 +0800

Overview

gobrave uses an outbox-based worker queue to manage all container lifecycle operations asynchronously. Instead of directly calling the container runtime (Docker/K8s), every operation — create, start, stop, and delete — is enqueued through the ContainerCreateWorker and processed asynchronously via the event bus.

This design provides:

Concurrency control — limits the number of simultaneous container creations via a semaphore.
Fault tolerance — failed operations are retried automatically via the outbox pattern.
Consistent state machine — all operations follow the same FSM-driven lifecycle.
Decoupling — the HTTP handler returns immediately, and the container operation happens in the background.

Architecture

Core Component Architecture

flowchart LR
 subgraph API[API Layer]
 H[HTTP Handlers]
 end

 subgraph Core[Control Plane]
 M[ContainerManager\nCreateByTemplate / Start / Stop / Delete / OnEvent]
 D[OutboxDispatcher\nPoll pending outbox]
 W[ContainerCreateWorker\nHandle create/start/stop/delete requests]
 R[RunRuntimeReconciler\nPeriodic monitor recovery]
 end

 subgraph Data[Data Layer]
 DB[(ContainerInstance + OutboxEvent + ContainerEvent)]
 end

 subgraph Runtime[Runtime Layer]
 RT[Docker / Kubernetes Runtime]
 end

 H -->|User request| M
 M -->|Tx: write instance + outbox request| DB

 D -->|Fetch pending requests| DB
 D -->|Publish Outbox*RequestEvent| W

 W -->|Execute Create/Start/Stop/Delete| RT
 RT -->|ContainerStarted/Exited/Failed/...| M
 M -->|FSM transition + event persistence| DB

 R -->|RecoverRuntimeMonitoring| RT
 R -->|Scan active instances| DB

This diagram shows three key loops:

Runtime Monitor Recovery After Restart

Tue, 11 Aug 2026 00:00:00 +0800

Overview

This document explains how gobrave restores runtime lifecycle monitoring after a process restart.

The current recovery path is based on:

ContainerManager.RunRuntimeReconciler(...)
ContainerManager.RecoverRuntimeMonitoring(...)
runtime Monitor(ctx, runtimeID) implementations
process-global MonitoringRegistry idempotency guard

The goal is to reattach monitoring for recoverable container instances and continue emitting runtime events into the normal state transition pipeline.

Why Recovery Is Needed

After service restart, in-memory monitor goroutines are lost. Without recovery, runtime state can change while persisted ContainerInstance status stays stale.

Kubernetes Runtime Architecture

Wed, 12 Aug 2026 00:00:00 +0800

Overview

This document explains the current Kubernetes runtime architecture used by gobrave.

It is based on the runtime implementation in:

internal/container_runtime/kubernetes/runtime.go
internal/container_runtime/kubernetes/monitor_v2.go

The runtime supports two workload kinds:

deployment (long-running service)
job (run-to-completion task)

Architecture Goals

Keep runtime monitoring efficient at scale.
Avoid duplicate monitor loops for the same runtime ID.
Convert Kubernetes workload state into stable gobrave runtime events.
Keep lifecycle behavior predictable for users (start, stop, delete, logs, inspect).

High-Level Flow

flowchart TD
 A[Create ContainerSpec] --> B[KubernetesRuntime.Create]
 B --> C{WorkloadKind}
 C -->|deployment| D[Create Deployment]
 C -->|job| E[Create Job]
 D --> F[Optional Service -svc]
 D --> G[Return runtimeID]
 E --> G

 H[Start or Recovery] --> I[KubernetesRuntime.Monitor]
 I --> J{MarkIfNotMonitoring}
 J -->|already monitoring| K[Return idempotently]
 J -->|new| L[Start shared informers once]
 L --> M[Register subscription kind namespace name]
 M --> N[Deployment or Job events]
 N --> O[Emit RuntimeEvent]
 O --> P[ContainerManager state transition]

Runtime ID Model

Runtime IDs are encoded as:

Event Bus Subscribers (event_handlers)

Tue, 11 Aug 2026 00:00:00 +0800

Overview

This document explains the user-facing architecture for all handlers subscribed to the shared event bus through the event_handlers DI group.

Registered subscribers in this group are:

NewRouteRegistryHandler
NewAppSessionEventHandler
NewDagRuntimeEventNotifier
ContainerCreateWorker

These handlers are all subscribed during startup by iterating the event_handlers group and calling bus.Subscribe(handler).

Subscription Architecture

flowchart LR
 subgraph Startup[Startup Wiring]
 C[BuildContainer]
 G[event_handlers group]
 B[event.Bus]
 end

 subgraph Subscribers[Subscribers]
 R[RouteRegistryHandler\nNewRouteRegistryHandler]
 A[AppSessionEventHandler\nNewAppSessionEventHandler]
 D[DagRuntimeEventNotifier\nNewDagRuntimeEventNotifier]
 W[ContainerCreateWorker]
 end

 subgraph Producers[Main Event Producers]
 O[OutboxDispatcher]
 M[ContainerManager / Runtime Events]
 DG[DAG Runtime]
 end

 C --> G
 C --> B
 G -->|for each handler| B

 O -->|OutboxCreateRequestEvent\nOutboxStartRequestEvent\nOutboxStopRequestEvent\nOutboxDeleteRequestEvent| B
 M -->|ContainerEvent| B
 DG -->|dag.RuntimeEvent| B

 B --> R
 B --> A
 B --> D
 B --> W

What Each Subscriber Does

1) NewRouteRegistryHandler

Primary role: keeps external route records in sync with App Session container lifecycle.

Container User Selection

Mon, 17 Aug 2026 00:00:00 +0800

Overview

This document explains when gobrave explicitly sets a container user and how that behavior differs between Docker and Kubernetes runtimes.

Where The User Value Comes From

The user value is populated while preparing a DAG node runtime spec.

Input variables:

USERID
GROUPID

If USERID is empty, gobrave does not set a runtime user.

When User Is Specified

Case 1: Docker Runtime

Condition:

runtime name is docker
USERID is present

Behavior:

Node Completion Bootstrap

Tue, 11 Aug 2026 00:00:00 +0800

Overview

NodeCompletionBootstrap is the startup wiring component that guarantees DAG analysis nodes are eventually finalized when their runtime containers reach terminal states.

It separates infrastructure concerns from DAG orchestration logic by:

constructing NodeCompletionCoordinator with cleanup policies
subscribing the coordinator to container lifecycle events
starting a background poll loop for reconciliation fallback

This ensures node finalization still happens after process restarts, missed events, or transient bus delivery gaps.

Architecture

flowchart LR
 subgraph Startup[Startup Wiring]
 C[DI Container Build]
 B[NodeCompletionBootstrap]
 BUS[event.Bus]
 end

 subgraph Coordinator[Reconciliation Engine]
 N[NodeCompletionCoordinator]
 P[Poll Loop every 2s]
 EH[Event Handler for ContainerStopped or ContainerFailed]
 end

 subgraph Data[Data Layer]
 CR[(ContainerInstance Repository)]
 AR[(AnalysisNode Repository)]
 end

 subgraph Runtime[Node Finalization]
 RE[RuntimeEngine CompleteNode]
 PUB[Publish DAG RuntimeEvent]
 end

 subgraph Cleanup[Container Cleanup]
 CM[ContainerManager Stop or Delete]
 CFG[container config policies]
 end

 C --> B
 B -->|Subscribe| BUS
 B -->|Start goroutine| N

 BUS --> EH
 N --> EH
 N --> P

 EH --> CR
 P --> CR
 CR --> AR
 AR --> RE
 RE --> PUB

 CFG --> B
 B --> CM
 N -->|on failed node| CM
 N -->|on successful node if enabled| CM

Startup Lifecycle

At application startup:

Outbox Dispatcher and Worker Concurrency

Tue, 11 Aug 2026 00:00:00 +0800

Overview

This document explains how RunOutboxDispatcher, OutboxDispatcher, and ContainerCreateWorker work together to implement queue backpressure and runtime concurrency control for ContainerInstance.

The key goals are:

Limit how many container create/start operations can run at the same time (maxConcurrency).
Limit how many create requests can wait in queue (maxPending).
Keep requests asynchronous by using OutboxEvent + event bus.

Components and Responsibilities

`RunOutboxDispatcher`

Starts the dispatcher loop in a goroutine.
Calls dispatcher.Start(context.Background()) asynchronously.

1
2
3


func RunOutboxDispatcher(dispatcher *OutboxDispatcher) {
 go dispatcher.Start(context.Background())
}

`OutboxDispatcher`

Polls pending outbox rows (ListPendingOutboxEvent).
Marks each request as processing before publish.
Publishes typed request events to the event bus:
- OutboxCreateRequestEvent
- OutboxStartRequestEvent
- OutboxStopRequestEvent
- OutboxDeleteRequestEvent

`ContainerCreateWorker`

Subscribes to bus events above.
Handles create/start/stop/delete asynchronously.
For create/start requests, uses capacity checks via acquireCapacityAndTransition.
Marks outbox sent on success, or back to pending on retriable failure.

Event Bus Flow

flowchart LR
 A[API / Manager enqueue] --> B[(go_outbox_event)]
 B --> C[OutboxDispatcher poll]
 C --> D[mark processing]
 D --> E[event.Bus publish]
 E --> F[ContainerCreateWorker Handle]
 F --> G{capacity + state valid?}
 G -- yes --> H[create or start container]
 G -- no --> I[keep request for retry]
 H --> J[mark outbox sent]
 I --> K[mark outbox pending]
 K --> C

`ContainerInstance` Status and Queue Behavior

Create request path

A create API path performs queue check and enqueue in a single DB transaction.
The transaction checks pending create requests against maxPending.
If pending create requests are already greater than or equal to maxPending, the transaction returns error and rolls back, so no ContainerInstance and no OutboxEvent are created.
If accepted, the same transaction writes:

ContainerInstance{status: pending}
OutboxEvent{Type: ContainerCreateRequest, Status: pending}

OutboxDispatcher publishes OutboxCreateRequestEvent.
ContainerCreateWorker handles the event and calls acquireCapacityAndTransition.

Capacity decision (`maxConcurrency`)

The worker counts active container instances occupying concurrency slots.
If active count is less than maxConcurrency, transition is allowed and container goes to creating, then running.
If active count is greater than or equal to maxConcurrency, capacity is denied and request is not executed in this round.

Result when denied:

Documentation on gobrave - Bioinformatics Analysis Platform

Quick Start

Overview

Prerequisites

1. Clone And Enter Project

2. Create Runtime Config

Configuration

Overview

Resolution Order

Config File Location

Core Sections

server

database

container

route

Architecture

Overview

High-Level Components

Runtime Composition

Container Management

Overview

Runtime Backends

Main Entities

Core API Groups

Image And Template

App Session Lifecycle

Runtime Monitoring

Lifecycle Model

Data Management

Overview

Core Data Objects

API Surface

Typical Data Workflow

Workflow Integration

Container Queue Monitoring

Overview

Architecture

Boot-Time Wiring for Fault Tolerance and Accuracy

Container Worker Queue System

Overview

Architecture

Core Component Architecture

Runtime Monitor Recovery After Restart

Overview

Why Recovery Is Needed

Kubernetes Runtime Architecture

Overview

Architecture Goals

High-Level Flow

Runtime ID Model

Event Bus Subscribers (event_handlers)

Overview

Subscription Architecture

What Each Subscriber Does

1) NewRouteRegistryHandler

Container User Selection

Overview

Where The User Value Comes From

When User Is Specified

Case 1: Docker Runtime

Node Completion Bootstrap

Overview

Architecture

Startup Lifecycle

Outbox Dispatcher and Worker Concurrency

Overview

Components and Responsibilities

RunOutboxDispatcher

OutboxDispatcher

ContainerCreateWorker

Event Bus Flow

ContainerInstance Status and Queue Behavior

Create request path

Capacity decision (maxConcurrency)

`server`

`database`

`container`

`route`

`RunOutboxDispatcher`

`OutboxDispatcher`

`ContainerCreateWorker`

`ContainerInstance` Status and Queue Behavior

Capacity decision (`maxConcurrency`)