# juxhouse/bela-resources architecture

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

- Interactive diagram: https://gitdiagram.com/juxhouse/bela-resources
- Repository: https://github.com/juxhouse/bela-resources

## Overview

##### What this “project” is (based on tree + README)
This repository is **not the BELA server/client source code**. It’s primarily:
- **Product documentation** (`README.md`, `Concepts.md`, `GettingStarted.md`, `HowTo.md`, `API.md`, `reference/*`)
- **Integration/updater scripts + guidance** for synchronizing:
- **Code repositories → BELA** (export structure/dependencies from repos)
- **APM/Telemetry → BELA** (service names + runtime dependencies)
- **SSO configuration references** (`reference/SSO-*.md`)
- **Health checks / deployment references** (`reference/Container-Health-Checks.md`, `reference/Client-Controlled-Deployment.md`)

##### BELA Platform (external system from the repo’s POV)
Implied by README:
- **BELA Web UI**: interactive dependency browsing, C4-like navigation
- **BELA Storage**: persists “single source of truth” modeled elements + ingested structures/dependencies
- **Auth/SSO integration**: Google / Microsoft Entra ID / Okta

##### Customer Environment
Explicitly described integration points:
- **Source code repositories** (multiple repos)
- **CI/CD pipeline** (GitHub Actions, GitLab CI, Jenkins, etc.) that runs:
- **Code synchronization steps** (see `CodeSynchronization.md`)
- **APM/Telemetry tools** (Datadog, Elastic APM, or others)
- Optional **manual modeling** via UI (human actors)

##### Updaters (integration executables)
As “adapter jobs” / “connectors”:
- `updaters/Datadog.js` and `updaters/Elastic-apm.js` (periodic scripts)
- Language-specific instructions under `updaters/*.md` (how to export code structure for .NET, Java Maven/Gradle, JS/TS, Ruby, Oracle, etc.)
- Shared config examples (`updaters/reference/*` like `bela.gradle`, `project.properties`)

**Goal:** show BELA as a system and all external actors/systems.

Include:
- Actor: **Architect/Developer** (uses BELA UI, models elements)
- Actor/System: **CI/CD** (push-based uploads)
- System: **APM/Telemetry** (pull data → uploader → BELA)
- System: **Identity Provider (SSO)** (Google/Entra/Okta)

- User → BELA UI (browse, model)
- CI/CD → BELA API (upload repo structure + ECD files)
- APM tool → updater script → BELA API (upload runtime dependencies)
- IdP → BELA (SSO auth)

Even without code, the docs imply these containers; keep them explicit:
- **Web Frontend (BELA UI)**
- **Backend API** (documented by `API.md`)
- **Ingestion endpoints** (can be a sub-container or component of API)
- **Data store** (graph-like store is plausible, but don’t guess product internals; label generically: “Architecture Model Store”)
- **Auth/SSO module** integrating with Google/Entra/Okta
- **Telemetry/APM ingestion module**
- **Repo/code ingestion module**

- UI ↔ API (query model, expand/collapse navigation)
- API ↔ Store (read/write model + dependencies)
- API ↔ IdP (SSO/OIDC/SAML flows—only if docs mention; otherwise “SSO integration”)
- CI/CD jobs → API (upload)
- Scheduled APM sync job → API (upload)

**Pipeline A: Code Synchronization**
- Source Repo → Export step (language-specific) → Artifact (ECD/structure payload) → Upload step → BELA API → Store → UI

With references:
- “3 steps” from `CodeSynchronization.md`
- Language-specific exporters configured per `updaters/*.md`
- CI/CD “optional step after pipeline” called out in README

**Pipeline B: APM/Telemetry Synchronization**
- Datadog/Elastic APM → Query script (`updaters/Datadog.js`, `updaters/Elastic-apm.js`) → Dependency payload → BELA API → Store → UI

- Repo contains `.bela/bela-custom-update.ecd` → CI/CD upload command (`updaters/reference/upload-example.md`) → BELA API (ECD endpoint) → Store → UI

Use `reference/Client-Controlled-Deployment.md` and `reference/Container-Health-Checks.md` to create a deployment boundary view:
- BELA (SaaS) vs Customer-managed deployment (if supported/outlined)
- Health checks: show load balancer → BELA containers → health endpoints

##### Relationships and interactions to emphasize (the “truth” of the system)
From README, BELA’s central behavior is: **ingest many sources → unify model → provide interactive exploration**.

- **Push ingestion** from CI/CD (code & ECD)
- **Pull/periodic ingestion** from APM tools (runtime truth)
- **Manual modeling** in UI for cross-org elements
- **Single source of truth** persisted centrally, powering UI queries
- **Dependency graph** as the primary data product (static dependencies from code + dynamic dependencies from APM)

Avoid over-specifying unknown internals (e.g., don’t claim “Neo4j” unless stated). Use neutral labels like “Graph/Model Store”.

##### Architectural patterns that are strongly implied here
- **Hub-and-spoke integration architecture**: BELA is the hub; repos/APM/CI are spokes.
- **Connector/adaptor pattern**: Updaters are adapters per tool (Datadog, Elastic) and per language ecosystem.
- **C4-inspired hierarchical model**: top-level domains → containers → components → code elements.

##### “Don’t overthink it”: break into many components
Given the repo is documentation + connectors, “best and most accurate” here means **maximizing clarity of integration surfaces**. Concretely:
- Split “BELA” into **UI / API / Store / Auth** at minimum.
- **scripts as first-class components**, not footnotes—because they’re the operative mechanism customers run.
- For each uploader, show **where it runs** (CI runner vs scheduled job host) and **what it talks to** (APM API vs BELA API).

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1 — System Context
%% =========================
subgraph "Diagram 1 — System Context (BELA as a hub)"
direction TB

U["Architect / Developer"]:::actor

subgraph "Customer Environment"
direction TB
REPOS["Source Code Repositories\n(multiple repos)"]:::customer
CICD["CI/CD Pipeline\n(GitHub Actions / GitLab CI / Jenkins)"]:::customer
APM["APM / Telemetry Tools\n(Datadog / Elastic APM / others)"]:::customer
JOBHOST["Scheduled Job Host\n(cron/runner)"]:::customer
end

subgraph "Identity Providers (SSO)"
direction TB
IDP["SSO Providers\n(Google / Entra ID / Okta)"]:::idp
end

subgraph "BELA Platform"
direction TB
BELA["BELA Platform"]:::bela
end

U -->|"browse+model"| BELA
CICD -->|"upload(push)"| BELA
APM -->|"telemetrysource"| JOBHOST
JOBHOST -->|"sync(pull→push)"| BELA
IDP -->|"SSO"| BELA
end

%% =========================
%% Diagram 2 — Container Diagram
%% =========================
subgraph "Diagram 2 — Container Diagram (BELA containers implied by docs)"
direction TB

subgraph "BELA Platform — Containers"
direction TB
UI["BELA Web UI\n(interactive dependency browser)"]:::bela
API["BELA Backend / Public API\n(upload+query surface)"]:::bela
AUTH["Auth / SSO Integration"]:::bela
STORE[("Architecture / Dependency Model Store\n(single source of truth)")]:::store

subgraph "Ingestion Modules (within API surface)"
direction TB
ING_CODE["Repo / Code Ingestion Module"]:::bela
ING_APM["Telemetry / APM Ingestion Module"]:::bela
ING_ECD["Diagram-as-Code (ECD) Ingestion Module"]:::bela
end
end

UI <-->|"interactivequery+write"| API
API -->|"read/write"| STORE
API <-->|"SSOflow"| AUTH
AUTH <-->|"federate"| IDP

API -->|"routeuploads"| ING_CODE
API -->|"routeuploads"| ING_APM
API -->|"routeuploads"| ING_ECD

CICD -->|"uploadcode+ECD"| API
JOBHOST -->|"uploadAPMdeps"| API
end

%% =========================
%% Diagram 3 — Ingestion Pipelines (core of this repo)
%% =========================
subgraph "Diagram 3 — Ingestion Pipelines (what this repo operationalizes)"
direction TB

subgraph "Pipeline A — Code Synchronization (CI-triggered)"
direction TB
A1["Repo Checkout"]:::customer
A2["Code Sync Exporters\n(language-specific)"]:::updater
A3["Structure/Dependency Payload\n(exported metadata)"]:::artifact
A4["Upload Step\n(CI job)"]:::customer

A1 -->|"input"| A2
A2 -->|"emit"| A3
A3 -->|"upload(push)"| A4
A4 -->|"POST"| ING_CODE

A2_DOTNET[".NET exporter instructions"]:::updater
A2_CLOJURE["Clojure exporter instructions"]:::updater
A2_JAVA_GRADLE["Java (Gradle) exporter instructions"]:::updater
A2_JAVA_MAVEN["Java (Maven) exporter instructions"]:::updater
A2_JAVA_OTHER["Java (Other) exporter instructions"]:::updater
A2_JS["JavaScript exporter instructions"]:::updater
A2_TS["TypeScript exporter instructions"]:::updater
A2_RUBY["Ruby exporter instructions"]:::updater
A2_ORACLE["Oracle exporter instructions"]:::updater

A2 -.-> A2_DOTNET
A2 -.-> A2_CLOJURE
A2 -.-> A2_JAVA_GRADLE
A2 -.-> A2_JAVA_MAVEN
A2 -.-> A2_JAVA_OTHER
A2 -.-> A2_JS
A2 -.-> A2_TS
A2 -.-> A2_RUBY
A2 -.-> A2_ORACLE

A3_GRADLE["Gradle config example\n(bela.gradle)"]:::artifact
A3_PROPS["Properties config example\n(project.properties)"]:::artifact
A3 -.-> A3_GRADLE
A3 -.-> A3_PROPS
end

subgraph "Pipeline B — APM/Telemetry Synchronization (scheduled pull → push)"
direction TB
B1["APM APIs\n(Datadog / Elastic)"]:::customer
B2["APM Sync Scripts\n(connectors)"]:::updater
B3["Runtime Dependency Payload"]:::artifact

B1 -->|"query(pull)"| B2
B2 -->|"transform"| B3
B3 -->|"upload(push)"| ING_APM

B2_DATADOG["Datadog connector script"]:::updater
B2_ELASTIC["Elastic APM connector script"]:::updater
B2 -.-> B2_DATADOG
B2 -.-> B2_ELASTIC
end

subgraph "Pipeline C — Diagram-as-Code (ECD)"
direction TB
C1["Repo: .bela/*.ecd\n(custom update file)"]:::customer
C2["ECD Upload Step\n(CI job)"]:::customer
C3["ECD Payload\n(ECD file format)"]:::artifact

C1 -->|"read"| C2
C2 -->|"upload(push)"| C3
C3 -->|"POST"| ING_ECD
end

ING_CODE -->|"persist"| STORE
ING_APM -->|"persist"| STORE
ING_ECD -->|"persist"| STORE
STORE -->|"power"| UI
end

%% =========================
%% Diagram 4 — Deployment / Ops Boundary (docs-justified)
%% =========================
subgraph "Diagram 4 — Deployment / Ops Boundary (configuration-centric)"
direction TB

subgraph "Customer Network / Edge"
direction TB
INGRESS["Ingress / Reverse Proxy\n(URL Prefix / Path Routing)"]:::ops
LB["Load Balancer"]:::ops
end

subgraph "BELA Deployment"
direction TB
HC["Container Health Check Endpoints"]:::ops
UI2["BELA UI Container"]:::bela
API2["BELA API Container"]:::bela
STORE2[("Model Store")]:::store

LB -->|"route"| INGRESS
INGRESS -->|"route"| UI2
INGRESS -->|"route"| API2

UI2 -->|"health"| HC
API2 -->|"health"| HC
API2 -->|"read/write"| STORE2
end
end

%% =========================
%% Legend / Notes (from repo guidance)
%% =========================
subgraph "Legend / Notes"
direction TB
L1["Hub-and-spoke integration:\nBELA is the hub; repos/APM/CI are spokes"]:::note
L2["Connector/adaptor pattern:\nUpdaters are adapters per tool and per language"]:::note
L3["Eventual consistency:\nmodels updated by CI-triggered uploads or scheduled sync"]:::note
L4["C4-inspired hierarchy:\ndomain→container→component→code elements"]:::note
L5["Arrow semantics:\nupload(push) vs query(pull) vs interactivequery"]:::note

L1_ASSETS["Documentation assets\n(images/diagrams)"]:::note
L1 -.-> L1_ASSETS
end

%% =========================
%% Click Events (docs, scripts, references, assets)
%% =========================
click BELA "https://github.com/juxhouse/bela-resources/blob/main/README.md"
click L4 "https://github.com/juxhouse/bela-resources/blob/main/Concepts.md"
click UI "https://github.com/juxhouse/bela-resources/blob/main/README.md"
click API "https://github.com/juxhouse/bela-resources/blob/main/API.md"
click ING_CODE "https://github.com/juxhouse/bela-resources/blob/main/CodeSynchronization.md"
click ING_ECD "https://github.com/juxhouse/bela-resources/blob/main/reference/ECD-File-Format.md"
click C2 "https://github.com/juxhouse/bela-resources/blob/main/updaters/reference/upload-example.md"
click ING_APM "https://github.com/juxhouse/bela-resources/blob/main/reference/Telemetry-APM-Tools.md"

click B2_DATADOG "https://github.com/juxhouse/bela-resources/blob/main/updaters/Datadog.js"
click B2_ELASTIC "https://github.com/juxhouse/bela-resources/blob/main/updaters/Elastic-apm.js"

click L1 "https://github.com/juxhouse/bela-resources/blob/main/README.md"
click L1_ASSETS "https://github.com/juxhouse/bela-resources/tree/main/assets/"
click L2 "https://github.com/juxhouse/bela-resources/blob/main/HowTo.md"
click L3 "https://github.com/juxhouse/bela-resources/blob/main/GettingStarted.md"

click A2_DOTNET "https://github.com/juxhouse/bela-resources/blob/main/updaters/.NET.md"
click A2_CLOJURE "https://github.com/juxhouse/bela-resources/blob/main/updaters/Clojure.md"
click A2_JAVA_GRADLE "https://github.com/juxhouse/bela-resources/blob/main/updaters/Java-Gradle.md"
click A2_JAVA_MAVEN "https://github.com/juxhouse/bela-resources/blob/main/updaters/Java-Maven.md"
click A2_JAVA_OTHER "https://github.com/juxhouse/bela-resources/blob/main/updaters/Java-Other.md"
click A2_JS "https://github.com/juxhouse/bela-resources/blob/main/updaters/Javascript.md"
click A2_TS "https://github.com/juxhouse/bela-resources/blob/main/updaters/Typescript.md"
click A2_RUBY "https://github.com/juxhouse/bela-resources/blob/main/updaters/Ruby.md"
click A2_ORACLE "https://github.com/juxhouse/bela-resources/blob/main/updaters/Oracle.md"

click A3_GRADLE "https://github.com/juxhouse/bela-resources/blob/main/updaters/reference/bela.gradle"
click A3_PROPS "https://github.com/juxhouse/bela-resources/blob/main/updaters/reference/project.properties"
click STORE "https://github.com/juxhouse/bela-resources/blob/main/reference/bela.properties.md"

IDP_GOOGLE["SSO: Google"]:::idp
IDP_ENTRA["SSO: Microsoft Entra ID"]:::idp
IDP_OKTA["SSO: Okta"]:::idp
IDP -.-> IDP_GOOGLE
IDP -.-> IDP_ENTRA
IDP -.-> IDP_OKTA

click IDP_GOOGLE "https://github.com/juxhouse/bela-resources/blob/main/reference/SSO-Google.md"
click IDP_ENTRA "https://github.com/juxhouse/bela-resources/blob/main/reference/SSO-Microsoft-Entra-ID.md"
click IDP_OKTA "https://github.com/juxhouse/bela-resources/blob/main/reference/SSO-Okta.md"

click API2 "https://github.com/juxhouse/bela-resources/blob/main/reference/Container-Health-Checks.md"
click UI2 "https://github.com/juxhouse/bela-resources/blob/main/reference/Client-Controlled-Deployment.md"
click INGRESS "https://github.com/juxhouse/bela-resources/blob/main/reference/URL-Prefix.md"

click L5 "https://github.com/juxhouse/bela-resources/blob/main/API.md"

%% =========================
%% Styles (color coding)
%% =========================
classDef bela fill:#1f77b4,stroke:#0b3553,color:#ffffff,stroke-width:1px
classDef store fill:#0b4f6c,stroke:#083142,color:#ffffff,stroke-width:1px
classDef customer fill:#2ca02c,stroke:#1b5e20,color:#ffffff,stroke-width:1px
classDef updater fill:#ff7f0e,stroke:#8a4b08,color:#ffffff,stroke-width:1px
classDef idp fill:#9467bd,stroke:#4b2b73,color:#ffffff,stroke-width:1px
classDef actor fill:#111827,stroke:#000000,color:#ffffff,stroke-width:1px
classDef artifact fill:#f2f2f2,stroke:#9e9e9e,color:#111827,stroke-width:1px
classDef ops fill:#17a2b8,stroke:#0b5d66,color:#ffffff,stroke-width:1px
classDef note fill:#fff3cd,stroke:#d39e00,color:#4b3b00,stroke-width:1px
```
