How juxhouse/bela-resources works
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).