Project Architecture — CORE / MODULES / APPS

Spell the company "Clustersco" — never "ClustersCo". The Bitbucket workspace and Docker Hub org are both clustersco. Everything follows one shape, so a new product, module, or client is a fill-in-the-template operation.

The three layers

• CORE — the platform foundation (Clustercore + shared modules). One base repo per core line (e.g. clustercore-bgv).
• MODULES — one repo per reusable module (bgv_templates, client_roles, policies), consumed by apps as git submodules under modules/.
• APPS — the assembled, shippable products (bgvchecker, clustersky). An app repo holds only its modules/, version.yml, app-config.yml, assemble.sh, and deploy files — never the full Clustercore runtime tree, which comes from Clustercore at assemble time.

Bitbucket layout (workspace clustersco)

Project	Repos	Layer
CLUSTERCORE	clustercore-* (one per core line)	CORE
CLUSTER-MODULES	one repo per module — underscore names (bgv_templates)	MODULES
CLUSTER-APPS	one repo per product (bgvchecker, clustersky)	APPS
TOOLS	cluster-cli (Go)	tooling

version.yml — the lockfile

At an app repo root; pins exactly what a build ships so any checkout is reproducible: the app version, the core (name + version + db_version), and each module's db_version.

app:    { name: bgvchecker, version: 1.4.0 }
core:   { name: clustercore-bgv, version: 3.1.8, db_version: 318 }
modules:
  bgv_templates: { db_version: 129 }
  client_roles:  { db_version: 102 }

One string identifies a release everywhere: git tag = version.yml app version = Docker image tag clustersco/<app>:<ver> (SemVer, no v). See Git & Versioning.

Modules as submodules + assembly

Modules live under modules/ as git submodules pinned to a TAG; the pinned commit must match the module's version.yml entry. app-config.yml sets clustercore_ref — the exact Clustercore tag to build on.

git clone --recurse-submodules git@bitbucket.org:clustersco/bgvchecker.git
cd bgvchecker && git submodule update --init --recursive
./assemble.sh   # clones core @ clustercore_ref, overlays modules/* at their tags, builds the image

:::caution Ordering rule Push a module's (or the core's) tag before the app that points at it, or git submodule update / CI fails with "reference is not a tree." Resolve a submodule (gitlink) conflict by checking out the intended tag inside the submodule — never --ours/--theirs. :::

Growth = fill in the template

New thing	The operation (never a redesign)
App	New app repo (submodules its modules) + Jira App project + Compass entry, in its Category
Core / line	New base + shared-module repos + a Jira Project Category + a <Core> Platform project
Module	New module repo + a Jira Component (mirror Compass) + Lead; submodule it into apps
Client	A Client/Account field value (+ per-client Version) — never a fork
Release	A new SemVer Version matching version.yml

See the Playbooks for the step-by-step version of each.