Brainforge Client Data Platform Documentation — Template Guide
This guide describes the Brainforge Client Data Platform Documentation Excel workbook template: what it is, when to use it, how to fill it out, and how to maintain it for future data teams.
What it is
The Brainforge Client Data Platform Documentation is a single Excel workbook (.xlsx) that serves as the single source of truth for a client’s data platform during an engagement. It captures:
- Business and industry context
- Naming conventions (schema, tables, columns, dashboards, campaigns)
- Data tools, contracts, and costs
- Inbound data sources and pipelines (sources → warehouse)
- Reverse ETL / outbound pipelines (warehouse → other systems)
- Core metrics, definitions, and lineage
- Mart layer (standard tab #11): Production Mart Catalog — per-table inventory when the engagement includes warehouse marts (e.g. Snowflake
PROD_MARTS.*, dbtmodels/marts/**). Optional companion: Subject areas glance tab—see data-platform-documentation-standard-tabs-sheets.md and marts-documentation-creation.md for alignment with generated metadata - Dashboards and reports (which may live in multiple systems)
- Teams (org structure; used as the source for Team dropdowns elsewhere)
- Data stakeholders and roles
The template is maintained in a master copy. For each new client data engagement, the team copies the template and renames it for that client, then fills it in as the project progresses.
When to use it
- At project kickoff for every data engagement (data foundation, ETL, analytics, BI, or combined).
- Ongoing as sources are onboarded, metrics are defined, and dashboards go live.
- Before handoffs so client and Brainforge have a shared reference.
Do not use it for non-data engagements (e.g. pure product or AI-only work) unless the scope later includes data platform elements.
Sheet-by-sheet guide
| Sheet | Purpose | What to fill in | Owner |
|---|---|---|---|
| How to Use This File | Overview and navigation | Update “Last Updated” and “Maintained by” when the doc is revised. | Engagement lead |
| Business Context | High-level client and industry context | Client name, industry, revenue drivers, relevance of our work, company size, market scope. Use the Guidance column for hints. | Engagement lead |
| Teams | Org structure; source for Team dropdowns | Team name, description, parent team (optional). Fill this first; then use data validation (List from this sheet) on the Team column in Data Stakeholders and anywhere else you want a Team dropdown. Reflects client org structure. | Engagement lead |
| Naming Taxonomy Conventions | Schema, table, column, dashboard, and campaign naming rules | Conventions agreed with the client (e.g. clientname_prod_domain, fct_/dim_ prefixes, campaign format). Add “Campaign Taxonomy / Offer Categories” row for client-specific categories (BOGO, LTO, etc.) if needed. | Data engineer |
| Data Tools & Costs | Stack, contracts, costs, recommendations | Status (Active/Proposed/Sunset), tool name, type, contract dates, owner, monthly/annual cost, pricing method, recommendation, notes. | Data engineer / PM |
| Data Sources | Inbound source systems and pipelines | Active flag, source name, description, owner, pipeline tool, method, frequency, duration, DW, destination, recommendation. Documents flows into the warehouse. | Data engineer |
| Reverse ETL / Outbound Pipelines | Data flows from warehouse to other systems | Pipeline name, source (e.g. mart/table), destination system, destination object, tool, frequency, owner, notes. Documents flows out of the warehouse (e.g. to CRM, marketing tools, operational systems). | Data engineer |
| Core Metrics & Lineage | Metric definitions, lineage, and glossary | Business domain, metric ID, name, channel, priority, definition, type, grain, product scope, aggregation, derivative flag, formula, source systems, marts model, data owner, primary stakeholder, refresh frequency, notes, Brainforge commentary, client commentary. This sheet is the single place for defining metrics and related business terms; no separate glossary sheet is needed. | Analytics / data lead |
| Dashboards | Dashboard and report inventory | System (e.g. Tableau, Looker, Google Sheets, Power BI), dashboard/report name, owner, priority, data category, has last updated at, refreshing frequency, link. Dashboards and reports may live in multiple systems; use the System column to record where each one lives. | BI / analytics |
| Data Stakeholders | Key contacts and roles | Name, email, role, team (use dropdown from Teams sheet), Brainforge team (Y/N). | Engagement lead |
| Production Mart Catalog | Production mart table inventory (dbt models/marts/ ↔ warehouse) — standard tab #11 when the engagement includes a mart layer | Google Sheet: one row per mart table with 18 columns (A–R): identity + description columns through Doc freshness, including driver fields (Build state, Cross-source, etc.). Populate from live warehouse metadata first, then dbt paths and mart catalog markdown (dbt_project/docs/*MART*CATALOG*.md or equivalent) / schema.yml. Headers and tab shape: data-platform-documentation-standard-tabs-sheets.md → Production Mart Catalog; implementation-agnostic automation rules: data-platform-doc-common.md → Mart catalog automation — behavior contract. | Data engineer |
| Subject areas (optional) | High-level map: lens ↔ warehouse schema ↔ “what lives here” | Short rows for executive or analyst navigation; pairs with Production Mart Catalog when both exist. | Data engineer / engagement lead |
Teams and data validation: Fill the Teams sheet with the client’s teams (optionally use Parent Team for hierarchy). Then set data validation on any column that should be a Team dropdown—e.g. Data Stakeholders, column Team—to allow List with source =Teams!$A$2:$A$50 (or the used range of team names). That keeps Team values consistent across the workbook.
Core Metrics as glossary: Core Metrics & Lineage is intended to double as the project glossary. Use the Business Definition column (and Notes / Caveats where needed) to define each metric and any business terms that matter for reporting. Avoid adding a separate Glossary sheet; keep definitions in Core Metrics so they stay in one place.
Formatting standards
These standards keep the workbook consistent and easy to read. When applying the template (e.g. via Claude in Excel), use:
- Font: Calibri 10pt for body; same for headers with bold.
- Header row (row 1): Bold, light gray fill
RGB 240,240,240(hexF0F0F0), center-aligned where appropriate. - Freeze panes: Freeze row 1 on every sheet so headers stay visible when scrolling.
- Column widths: Set explicitly so headers and key columns (e.g. descriptions, definitions) are readable; avoid default narrow widths.
- Numbers: Currency columns use
$#,##0or$#,##0.00; date columns usem/d/yyyy. - Tab colors (optional): How to Use = blue, Business Context = green, Teams = green, Naming/Tools/Sources = orange, Reverse ETL = orange, Metrics/Dashboards = purple, Stakeholders = gray.
Customization guidance
- Client-specific sheets: Clients may need extra sheets (e.g. offer taxonomy, exec dashboard scratchpad, metrics from an Airtable export). Add these after the standard sheets and name them clearly (e.g. “Exec Dashboard scratchpad”, “SOURCE_MEDIUM - Metrics Airtable”). Do not add them to the master template unless they become standard for most clients.
- Extra columns: If a client needs columns that are not in the template (e.g. “BF Granted UI Access”, “Connector Built”), add them to the client copy only. Document the meaning in the sheet or in the “How to Use” sheet if it affects multiple tabs.
- Renaming columns: Avoid renaming standard columns in the template; in client copies, rename only when the client’s terminology is fixed and agreed.
Versioning and file naming
- Master template: Keep one canonical template (e.g. “Brainforge Client Data Platform Documentation.xlsx”) with generic placeholders and the “How to Use This File” sheet. Do not put client-specific data in the master.
- Client copies: Save as
Brainforge [Client] Data Platform Documentation.xlsx(e.g. “Brainforge LMNT Data Platform Documentation.xlsx”). Store in the client’s repo, vault client folder, or shared drive as per project norms. - Updates: When the template structure or sheets change, update the master and the playbook (this guide and the prompts file). Existing client workbooks can be updated manually or by re-applying the relevant prompts and then re-adding client-specific content.
Template migration and client copies
When the canonical template changes (new standard tab, new row-1 headers, optional tab layout):
- Re-copy from master when many tabs or headers shift at once: open the latest Brainforge Client Data Platform Documentation template, then merge over your client’s filled cells (or use kickoff-style copy for a net-new file). This is safer than reconstructing every column by hand.
- Add a tab manually for optional sheets (e.g. Subject areas) when an existing engagement needs that tab mid-project; use the SSoT for exact tab name and header row. For Production Mart Catalog (standard #11), follow the same SSoT when repairing a workbook that predates the tab.
- Small or cosmetic changes (formatting, one-sheet fixes) can use data-platform-documentation-template-prompts.md (Claude in Excel) without a full re-copy.
Changelog habit: Note material template updates in the master’s How to Use or in internal release notes. Example: 2026-04-22 — SSoT documents Production Mart Catalog as standard tab #11 (18 row-1 headers); Excel exports may show Reverse ETL - Outbound Pipelines as the reverse-ETL tab (hyphen replaces slash per Excel rules)—same standard tab; see data-platform-documentation-standard-tabs-sheets.md.
Related playbook assets
- Claude in Excel prompts: data-platform-documentation-template-prompts.md — step-by-step prompts for the Claude in Excel add-in to create or update the template (e.g. add “How to Use”, fix typos, apply formatting).
- Technical planning:
standards/06-technical-planning/— for full technical design docs (TDD) that reference this workbook. - Data workflows:
standards/03-knowledge/engineering/workflows/— marts documentation, metrics dictionary, table profiling.