home
docs / architecture & background

Architecture & background

why these agents exist, the platform they are trying to build, and where everything runs

Why these agents exist

Every data-platform engagement repeats the same pipeline: weeks of discovery meetings distilled into requirements by hand, a modelling phase done in whiteboards and spreadsheets, and then a build phase where each table is specified, built and tested one ticket at a time. The expensive parts are not the judgement calls — they are the transcription, the cross-referencing, the "who approved this?" archaeology, and the mechanical translation of an agreed design into working tables.

This platform automates exactly those parts, and deliberately nothing more. The architectural decision (recorded as ADR-001 in the repo) is deterministic workflows that call LLMs only for the genuinely fuzzy steps — not one autonomous agent in a free-running loop. A state machine owns control flow, so runs are predictable, debuggable and resumable. LLM-powered agents handle extraction, generation and diagnosis; everything mechanical is deterministic code with no hallucination surface; every side effect goes through a tool; and guard rails (token and wall-clock budgets, a stall detector, human-in-the-loop gates) bound the whole thing.

The runtime is provider-agnostic by design — Azure OpenAI or Anthropic, selected per client — because a consulting product has to run on whatever the client's estate allows, not on one vendor's hosted agent platform.

The target: a Medallion lakehouse on Microsoft Fabric

Everything the agents do converges on one deliverable — a governed Bronze → Silver → Gold lakehouse in Microsoft Fabric, where every transformation is a declarative Delta-Gen YAML file and the repository layout follows the delta-gen-template reference structure. This is the map to keep in mind while reading everything else on this site.

Source systems client databases & files MICROSOFT FABRIC LAKEHOUSE Bronze raw landing zone source fidelity preserved Silver validated · cleansed conformed entities Gold dimensional models business-ready facts every transformation is a declarative Delta-Gen YAML file — one per table, tests compiled from the same YAML Semantic model Power BI · analytics

One nuance worth knowing: discovery and modelling are platform-agnostic — a requirements catalogue and a logical model could target any stack. It is the build suite that commits to Fabric, turning mappings into lakehouse tables through Delta-Gen. Swapping the target platform means swapping build, not the pipeline.

Where everything runs

The agents sit between the client's estate and the engagement record. Artefacts come in from SharePoint and Teams, source systems are profiled read-only, and the build loop works tickets from Azure DevOps against Fabric — building, observing and testing until the table is right, then raising the PR back in ADO. Orchestration is plain Python that can run locally, in Container Apps or in Functions; Azure AI Foundry is used purely as a model host — the agentic behaviour is the platform's own orchestration, never a hosted agent runtime.

SharePoint · Teams transcripts · emails · questionnaires Source systems client databases (read-only) Microsoft Fabric lakehouse · notebooks · DQ tests Azure DevOps tickets · engagement repo · PRs artefacts in profile (read-only) run · observe · test ticket in · PR out AGENT RUNTIME plain Python — runs locally · Azure Container Apps · Functions Discovery artefacts → catalogue + decisions Modelling catalogue → model → mappings Build mapping → tested table → PR Azure AI Foundry model host — inference only (or api.anthropic.com) LLM calls writes, with citations Engagement repo (git / ADO) requirements-catalog.yaml · decision log · mapping files rendered This console catalogues · run scorecards · docs Fabric data agents — planned natural-language querying over the lakehouse the agents build

The engagement repo is the system of record — every catalogue item, decision and mapping lands there with citations, and this console is rendered straight from it. The dashed box is the roadmap: once Build has shipped the lakehouse, Fabric data agents would let the client query it in natural language — closing the loop from "first conversation" to "ask your data anything".

← Docs home

the three suites and how they connect

Build deep-dive →

the 14-step workflow and its self-correction loops

Discovery deep-dive →

stages, agents, code-enforced guarantees