Documentation

Audience: developers & AI agents · Last reviewed: 2026-07-12

Curated, reviewed documentation for the Beta-Calco / ConfigBox project. These files are written to serve both human developers and AI coding agents — the same doc is the source of truth for both. The repo-root CLAUDE.md is a thin map that points here; the detail lives in this folder.

New to the codebase? Start here

What this is. Beta-Calco is a specification-grade architectural lighting manufacturer, and this repo is its website. Technically it's a Joomla 5 site whose business logic lives almost entirely in the ConfigBox product configurator (built on the Kenedo MVC framework). It wears three hats at once:

• a marketing website (homepage, products, projects, news, designers, resources);
• a product configurator — visitors build a luminaire from options and get a live product code, spec sheet, and photometric files; and
• a B2B sales & operations tool — agents build quotes, and the back office runs pricing and bills of materials, syncing to Pipedrive (CRM), Infor (ERP), and Google Sheets.

Beta-Calco's own code is a customization overlay on top of the third-party product — that's the single most important thing to internalise (the golden rule below).

Your first day — read these in order:

1. configbox/architecture.md — how the code is laid out and the one rule that prevents breakage: only edit docroot/components/com_configbox/data/customization/. Start here.
2. configbox/environment.md — get the site running locally (there's a first-time setup section).
3. configbox/migrations.md — how DB/schema changes are made (numbered, auto-run migrations — never hand-edit the schema).
4. configbox/sef-links.md — how a custom page gets a clean URL.
5. standards/writing.md — how we document; you keep docs current as you work.
6. features/customer-groups-and-visibility.md — the access model. Worth reading early: the customer group decides currency, pricing, permissions and which products exist for a user at all, so it explains a lot of "why can't I see this?".
7. scheduled-jobs.md — most of the integration work happens unattended. Skim it before running any CLI script by hand; several are destructive and a few email real people.
8. quotes/ — the central business object. Almost everything on the B2B side hangs off a quote, so this is the vocabulary the Pipedrive, follow-up and Infor docs assume.
9. Then browse the feature / system docs for the area you're touching — Quote Follow-Up, Pipedrive, Infor / ERP, Google Sheets, Testing.

Hit a rough edge? Check _known-issues.md (docs/_known-issues.md) before assuming it's news — the things already known to be wrong, risky or half-finished are listed there with what fixing them would involve.

Keep the glossary to hand — the docs use a lot of Beta-Calco / ConfigBox shorthand (SEF, RSM, OOT, CPQ, BOM, nudge, magic link, serial…).

Want to see what the system actually does from a user's seat? The operator Admin Guide (admin-guide/README.md) is the fastest tour of the real screens and workflows.

Two audiences

Documentation is split by who reads it — two roots, kept apart on purpose (and, once the site is scaffolded, two separate Docusaurus instances):

• Reference docs — docs/ (here). For developers & AI: architecture, code, data model, deployment, testing. This is the source of truth; CLAUDE.md is a thin map that points in.
• Admin Guide — admin-guide/README.md. For operators/admins doing data entry and settings: plain-language, task-oriented how-tos, deliberately free of code and internals.

The standards govern both. Don't leak dev internals into the Admin Guide, and don't bury an operator how-to inside a reference doc.

How this system is organized

• CLAUDE.md (repo root) — always-loaded orientation + the few rules that prevent breakage, plus an index. Keep it short; link out instead of duplicating.
• docs/ (here) — one file per topic/subsystem. Detailed, but each doc stays focused on a single subject so it's easy to find, read, and keep accurate. Every top-level entry is one of a few kinds — a foundation/platform, feature, system, integration layer, cross-cutting area, or meta (see standards/features.md).
• admin-guide/ (repo root) — the operator Admin Guide (above), grouped by system to mirror docs/.
• notes/ (repo root) — informal/personal scratch (infra steps, SQL snippets, VPN setup). Not curated. When a note becomes something the team relies on, promote it into docs/.

Doc conventions

How we write docs — the doc shape, writing principles, what not to include, the Docusaurus conventions, and pre-commit checklists — lives in standards/: writing.md (the base every doc follows), features.md (feature/System docs), and admin-guide.md (the operator Admin Guide).

How to add a doc

1. Create the doc following the standards (start with writing.md).
2. Add a one-line entry to the Index below and (if it's high-value) to the index in CLAUDE.md.
3. If the topic is tied to a code area, link the doc from a comment at the top of the relevant file, and link the code back from the doc.

Index

Reference docs (docs/), in sidebar order — each row is one of the top-level kinds. The operator-facing Admin Guide (admin-guide/README.md) is the separate counterpart (see Two audiences).

Doc	Kind	What it covers
_known-issues.md (docs/_known-issues.md)	planning	Known issues & follow-ups — things found while documenting that look wrong, risky or half-finished, ordered by severity, each with what it is and what fixing it involves. Start here before assuming a rough edge is news.
monitoring.md	cross-cutting	How the site reports on itself — CloudWatch metrics via a deferred database queue drained by cron, the namespaces, the Infor/VPN probes, the log types that answer "why did this integration fail?", and an explicit list of what nothing is watching.
scheduled-jobs.md	cross-cutting	What runs unattended — the 67 docroot/cli/ scripts by area, the schedules that are actually recorded (the crontab lives on the server, not here), which scripts are destructive or email real people, where the concurrency guards are, and which ones are dead. Read the warnings before running any of them by hand.
glossary.md	reference	Glossary — the Beta-Calco / ConfigBox terms and acronyms used throughout (ConfigBox, Kenedo, overlay, SEF, RSM, OOT, CPQ, BOM, Infor, nudge, magic link, serial…). Read alongside everything else.
configbox/	foundation	ConfigBox / Kenedo platform: the architecture (core vs. customization, request lifecycle, override mechanisms, conventions — start here), DB migrations & the KenedoDatabase API, clean SEF URLs (incl. the /cb-api/… endpoint), and the local dev / deploy environment
features/	feature	Standalone features (one focused doc each): tracking — unified Meta Pixel / GA4 / Pinterest analytics via a manager + adapters, tags loaded through GTM, gated on the Cookiebot CMP; product HTML embed — admin-uploaded HTML shown in a sandboxed iframe above a product's configurator-page materials section; customer groups & visibility — the group model (currency, permissions, discounts, agent status) and the xref gating that decides who sees which products and files; discontinued products — retiring a product without taking its spec sheet away
quotes/	system	The quote — the site's central business object: the object graph (opportunity → quote → position → selection → BOM), the non-unique serial, revisions vs alternatives, who may act on a quote, and where Pipedrive/follow-up/Infor attach. Spokes: data model (incl. the naming traps) and lifecycle & pricing (four independent status axes; totals are computed, never stored).
bom/	system	BOM & CPQ — how a configured luminaire becomes a parts list. The site never calculates a BOM; Infor does. Two strategies: the slash method (match the configuration code to an existing Infor item, serve its cached BOM) and CPQ (Infor's rule engine, over SOAP — a third Infor access path). Spokes: position BOMs (the resolution ladder + bom_status), the BOM cache, Infor CPQ, and the BOM REST API the site exposes.
product-documents/	system	Spec sheets & product PDFs — the generic (cached, four variants) vs configured spec sheet, the dompdf pipeline, and a disk cache with no automatic invalidation. Spokes: the downloads page and performance data.
quote-follow-up/	system	Quote Follow-Up System (hub → spokes): the no-login landing page + magic-link/Link API, the "due for a nudge" cadence sheet, and the quote-stage-sync sheet
pipedrive/	integration	Pipedrive integration (hub → spokes): quotes ↔ deals — the flows & foundational layer (hub), the outbound deal-field reference, the admin/ops manual, the go-live runbook, testing, and read-only API lookups
google-sheets/	integration	Google Sheets layer (hub → spokes): one service account behind 30+ consumers — the shared client, the <id>#<gid> sheet picker, the memcached/APCu caches and the failure modes everything inherits, plus a full consumer inventory and settings reference
infor/	integration	Infor / Syteline ERP (hub → spokes): the two access paths — an authenticated IDO REST API (token cached 48h, CloudWatch-monitored) and a direct MSSQL connection over the VPN (connection reuse + bounded retry) — which consumer uses which, and why "Infor is down" is never one thing
testing/	cross-cutting	Testing (hub → docs): the e2e standard (coverage at every feature), the guide (accounts, settings, patterns), the reusable test-support API, a catalog of every spec, and the concepts primer
standards/	meta	Documentation standards (hub → docs): how we write docs — the base writing.md, plus features.md (feature/System docs) and admin-guide.md (operator docs)

Add new rows here as docs are written. Candidates not yet documented: price-list sync, order tracking & Syteline sales orders, the costing sheet / margin analysis, and the configurator itself (products, questions, answers, the product tree). (Some have draft notes under notes/.)