britecore_docs

A shared documentation and architecture hub for the BriteCore ecosystem.

This site brings together the patterns, repo boundaries, lineage rules, and reporting concepts that make the wider data platform easier to understand across projects.

It is designed as a bridge layer: the source repositories remain the canonical home for implementation detail, while this project explains how the pieces fit together.

What this site is for

This documentation is intended to help with:

• understanding repo roles and source-of-truth ownership
• tracing how the same business object appears across CSV, API, and SQL/report layers
• documenting data flow, grain, and relationship patterns
• onboarding new contributors to the broader reporting and integration model
• describing common reporting workflows without duplicating raw implementation logic

Start here

If you need to answer a business question

• Reporting Logical Layer — how the reporting layer is modeled
• Reporting Playbook — how to define, validate, and deliver a report
• SQL Reporting Cookbook — practical SQL patterns and validation queries
• Report Metadata Examples — current MCP-style report definitions and sheet patterns
• Field Discovery Checklist — the structured way to find the right fact and join path

If you need to understand the ecosystem

• Architecture — how these repos fit together
• Consolidation Principles — the editorial rule for this repo
• Source-of-Truth Matrix — which repo owns which concern
• CSV / API / SQL Mapping — how raw CSV names, API payloads, and SQL/report views align
• Access Mode Decision Matrix — when to use CSV, API, or SQL/report views
• Bridge Table Guide — how relationship tables differ from base entity tables and why they multiply
• Field Mapping Cheat Sheet — side-by-side mappings for the main CSV/API/SQL entity shapes
• Join Chains and Lineage — the repeatable join patterns that connect policies, claims, contacts, and properties
• Query Quickstarts — concrete SQL and API patterns for common business questions
• Status and Enum Dictionary — normalized meanings for active, deleted, terminated, claim state, policy state, and role flags
• Relationship Catalog — the major parent-child and bridge relationships across policies, claims, contacts, and properties
• Domain Reference — the domain-level map for claims, policy/revision records, contacts, properties, payments, and related objects
• Claim Domain Guide — the practical lineage and join map for claim data
• Policy and Revision Domain Guide — the practical lineage and join map for policy and revision data
• Contact Domain Guide — how contact records connect to claims, revisions, and communication child tables
• Property and Risk Domain Guide — how property/risk data connects to revision and mortgagee records
• Payment and Billing Domain Guide — how payment headers and item-detail data are linked across the platform
• AI Workflow Guide for Other Repos — how to work in the other BriteCore repos without duplicating implementation in the docs repo
• Repo-by-Repo AI Usage Guide — a practical guide for using AI in each project without losing repo boundaries
• Reconciliation Checklist — a repeatable validation flow for comparing raw CSV, API, and report-layer records
• Common Gotchas and Anti-Patterns — the recurring mistakes that make BriteCore joins and mappings look inconsistent
• Record Trace Workflow — how to trace a policy, claim, or contact end to end across layers
• Data Flow and Grain Guide — how raw data flows into reporting and why grain matters
• BriteCore Status and Cancellation Semantics — how status and cancellation reasons differ across source systems
• Lineage Guide — how revision, policy, claim, and property IDs connect
• Repo Selection Guide — how to choose the right repo for a task
• Help Center Insights — what the public BriteCore product documentation says about the platform structure
• Data Storage and Handling — how data moves through API, logical SQL/reporting, and CSV extracts
• Data Lineage Reference — the end-to-end object lineage across policy, claim, revision, item, property, and contact data
• Entity Relationship Matrix — the shared IDs and join chains that define the logical reporting graph
• SQL Reporting Project — where report SQL and report docs now live
• Project Map — what each project is best at
• Source Registry — canonical repos and entry points
• Decision Matrix — choose the right repo for the task
• Glossary — shared terms, concepts, and reporting vocabulary
• Operating Manual — how the team works across the stack

If you are onboarding or getting set up

• Onboarding — the recommended first steps
• Quickstarts — repo-specific setup and usage patterns
• Ingestion Workflow — how to add or refresh cross-project docs

Common task flow

1. Clarify the business question and target grain.
2. Use britecore_mcp to find the logical reporting tables and fields.
3. Validate raw relationship assumptions with britecore-csv-loader when needed.
4. Use britecore_sdk for live API access when the task requires it.
5. Move cross-source reporting logic into PolicyReporting when a service layer is needed.
6. Document the final pattern here once it is stable enough to reuse.

Recommended operating model

1. Keep detailed implementation docs in the source repos.
2. Use britecore_docs for shared architecture, onboarding, and cross-project guidance.
3. Link back to source files when the canonical implementation details live elsewhere.
4. Promote stable cross-repo patterns into this project once they become reusable.
5. Prefer decision-oriented documentation over raw duplication.

Canonical ownership rules

• If the user needs the source-of-truth API or SDK guidance, start in britecore_sdk.
• If the user needs how the ecosystem fits together, use britecore_docs.
• If the user needs runtime or report-definition behavior, start in the owning project (britecore_mcp, britecore_sql_reports, etc.).

For the SDK in particular, the canonical documentation set is the SDK repo itself, and britecore_docs should summarize it rather than reproduce it.

Current state

This hub includes:

• repo registry and architecture pages
• onboarding and quickstart guides
• reporting logical-layer references and cookbook guidance
• a dedicated SQL reporting project page
• a cross-project operating manual
• project summary pages for each local source repo