Databricks Partner Well Architected Framework: How to Actually Build and Submit a Solution With It

Most partner-facing frameworks are documentation you skim once and never open again. The Databricks Partner Well Architected Framework is not that, because it contains one decision that silently determines everything downstream: which deployment model your product uses. Get that wrong and you can build a technically excellent solution that is structurally incapable of earning the partner benefits you built it for.

I found this out the practical way. I used the PWAF to design and submit a Databricks solution accelerator for WorldLink, and the framework was genuinely useful, but the most valuable thing in it was not a pattern or a diagram. It was a single sentence buried in the Customer Managed deployment page.

This post is the guide I wanted when I started: what the PWAF is, which of the three partner tracks you belong to, what the four pillars actually demand, how to choose between the four deployment models, and which requirements are hard gates versus suggestions.

The training is worth the hour, but it teaches you the map, not the terrain. What follows is the terrain.

01What is the Databricks Partner Well Architected Framework?

The Partner Well Architected Framework (PWAF) is Databricks' architecture guide for technology partners building products, integrations, and data shares on the Databricks Data Intelligence Platform. It is published by Databricks Labs at databrickslabs.github.io/partner-architecture and organized around three partner types and four architectural pillars.

The framing matters. Databricks explicitly positions the PWAF as an extension of the cloud Well Architected Frameworks (AWS, Azure, GCP) and the Databricks Lakehouse Architecture, applied to problems those frameworks do not cover: multi-tenant SaaS architectures, customer data integration, marketplace distribution, and partner attribution.

That last one, attribution, is the tell. The cloud frameworks care whether your system is reliable and secure. The PWAF also cares whether Databricks can see your product working, because partner economics depend on measurable joint impact. Read the whole framework through that lens and a lot of otherwise-arbitrary requirements start making sense.

One practical note before you start: the PWAF is deliberately built for AI-assisted development. Every page has a copy-link action and an AI assistant dropdown with pre-loaded prompts, and the site publishes two machine-readable context files, an llms.txt site map and an ai-context.txt guidance file. If you are going to work through the framework with Claude or Cursor, point the tool at those files first instead of pasting pages one at a time.

02Who the PWAF is for: the three partner tracks

Before reading anything else, work out which track you are in, because the technical standards differ per track and you will waste time reading requirements that do not apply to you.

The boundaries blur in practice. A notebook-based solution accelerator that a customer runs in their own workspace is closest to the Built-On track under the Customer Managed deployment model, even though it feels nothing like a SaaS product. That mismatch is worth thinking about early, and I will come back to it.

One thing the PWAF is clear about: the framework is technical guidance, not membership. To get go-to-market benefits, co-sell, and program incentives you have to be an active member of the Databricks Partner Program, and validation requests go through the Partner Portal. Building well and being a partner are separate steps, in that order or not.

03The four PWAF pillars, and which ones actually gate you

Databricks defines four pillars:

1. Architectural Best Practices. Design principles, repeatable patterns, reference architectures, and implementation guidance.
2. Defined Technical Standards. Per-partner-type requirements that must be met for validation and program participation, with a stated path to validation.
3. Measurement and Attribution. Continuous measurement of adoption and impact, and partner attribution through telemetry.
4. Operations and Lifecycle Management. Monitoring, automation, runbooks, access management, and continuous improvement workflows.

Here is the part nobody tells you: engineers spend roughly all of their effort on pillar 1 and almost none on pillar 3, and pillar 3 is closer to a gate.

Pillar 1 is fun. It is diagrams, patterns, and design debates. It is also where you have the most latitude, because "good architecture" has many valid shapes.

Pillars 2 and 3 are checklists with binary outcomes. Did you embed a programmatic User-Agent? Did you register your data assets in Unity Catalog? Is OAuth implemented, or are you still passing personal access tokens around? These are yes-or-no, and they are cheap to do early and expensive to retrofit.

Pillar 4 is the one that gets deferred to "after we ship," which is why so many partner solutions have no runbook, no documented upgrade path, and no support boundary. The Customer Managed guidance is blunt about this: define clear boundaries for support, provide clear versioning for all artifacts, document upgrade paths and breaking changes, and consider backward compatibility for long-term customers. That is a pillar-4 to-do list, and it takes a day.

04Connected ISV: the requirements that are genuinely mandatory

If you are connecting an existing product to Databricks, the integration requirements page is the highest-value page in the entire framework. It is short and it is specific. These are the hard requirements.

OAuth 2.0 is mandatory, and personal access tokens are not a strategy

OAuth is mandatory for all ISV partner integrations and is the standard mechanism for secure production authentication. Two flows are supported:

• User-to-machine (U2M). A browser-based OAuth flow where the user authenticates with their own identity and your app acts on their behalf. Relevant docs cover JDBC, ODBC, OIDC U2M, and token federation.
• Machine-to-machine (M2M). Client credentials with service principals, so jobs, services, and scripts reach Databricks with no signed-in user. This covers Workload Identity Federation, account token federation, and Databricks OIDC M2M.

The security and lifecycle guidance is standard but worth quoting as a checklist, because reviewers will look for it: request least-privilege scopes, persist tokens securely, rotate refresh tokens, use PKCE, never log tokens and ensure redaction, support revocation, and provide a clear disconnect and re-auth experience.

That last item is the one I see skipped most. Plenty of integrations can connect. Far fewer can cleanly disconnect.

Unity Catalog registration is not optional if you touch data

The rule is broad: if an ISV integration reads, writes, stages, or manages any type of data asset, the integration must register and operate on those assets in Unity Catalog. "Data asset" is defined widely too, covering structured and tabular data (tables, views, materialized views, metric views, UDFs), unstructured files (images, documents, logs, binaries, ingestion files), and ML models.

Practically, this means three-level namespacing (<catalog>.<schema>.<table>) everywhere, no side-channel storage that bypasses governance, and metadata access that complies with the Databricks Acceptable Use Policy.

Telemetry: one string, programmatically set, verifiable in a system table

This is the requirement that most directly serves the Measurement and Attribution pillar, and it is a small amount of work with outsized consequences.

You must programmatically embed a stable partner User-Agent identifier in every Databricks API call, driver or SQL connection, SDK or connector call, job, CLI invocation, or other integration request originating from your product. The format is built from isv-name, product-name, and product-version, separated by underscores. Each product or integration needs a distinct value.

Two details matter more than the format:

You cannot outsource it to the customer. The framework says it plainly: partners must set this value programmatically in the connection code path, and you cannot rely on joint customers to configure it themselves. It calls this a strict requirement.

You can verify it yourself. The Source column in Query History reflects the User-Agent used by the partner application, and for full coverage across workloads you query the audit system table:

SELECT *
FROM system.access.audit
WHERE event_time > current_timestamp() - INTERVAL 2 days
  AND lower(user_agent) LIKE '%<your-user-agent>%';

Run that before you submit anything. If it returns nothing, your attribution does not exist, whatever your architecture diagram says.

Genie attribution has specific UI requirements

If your product surfaces Genie output, four things are required: a visible "Powered by Genie" label wherever Genie-generated content appears, a citation linking directly to the Genie Space that produced the result (constructible from the space_id returned by the Genie API), any links in the Genie response surfaced and navigable, and the same attribution in product surfaces like settings or integration dialogs and in your documentation.

And a hard one for AI products: agent products must invoke Genie via MCP, and agent workflows that do not use the Genie MCP will not be validated. If you built an agent that talks to Databricks through a bespoke SQL path, that is a rewrite, not a tweak.

Documentation is a deliverable, not an afterthought

Partners must provide written documentation that lets a customer connect the product to Databricks, and the framework specifies its contents: prerequisites, the Databricks privileges the connecting user or service principal needs, which authentication types are supported, and step-by-step setup for each supported auth type. PDF is accepted at submission, live docs on your site are preferred.

I would go further and write this document first. It forces you to answer "what privileges do we actually need" before you have hard-coded an over-privileged service principal into a demo.

Product categories change the specifics

Beyond the common requirements, the framework splits Connected ISV guidance into five product categories: Data Engineering and Ingestion, AI Agents and Tools, Business Intelligence, Governance and Observability, and Apps and Dev Tools. Find your category and read its page, because category-specific best practices are additive to the shared requirements, not a substitute.

05Data Collaboration: productizing data instead of shipping software

The Data Collaboration track assumes your data already exists in Databricks and is registered in Unity Catalog. It does not cover upstream ingestion or ETL, which is a useful scoping decision.

Sharing breaks into named patterns:

The engineering advice in this track is less about protocols and more about making data usable, and it lands on metadata. Unity Catalog lets you attach table and column descriptions, tags, business terms, and relationships, and the framework ties this directly to AI readiness: when Genie can read complete and accurate metadata, users can query and explore your data in natural language.

That is a real incentive change. Metadata used to be documentation hygiene you did for humans who mostly ignored it. Now it is the interface that determines whether natural-language querying works on your data product. If you share a table with cryptic column names and no descriptions, you have shipped a dataset that AI tooling cannot use well, and your consumers will notice.

Two more operational notes worth acting on: enable Change Data Feed where incremental reads and automation matter, and plan schema evolution and backward compatibility so your updates do not break consumer workloads. A shared table is an API. Breaking changes behave like breaking changes.

06Built-On ISV: the five-layer application architecture

If Databricks is your backend, the framework expects a specific application shape. For most Built-On products you build an application that sits between your end users and the platform, in five layers:

1. Client Layer        Browser frontend (React, Angular, Vue), renders UI,
                       makes authenticated API requests
2. Authentication      OAuth 2.0 / OIDC with your identity provider,
                       user auth and session management
3. Backend Layer       Server-side API routes, validates sessions, manages
                       tokens, proxies ALL Databricks API calls
4. Data Layer          Application database (PostgreSQL, MySQL): users,
                       organizations, encrypted credentials
5. Databricks          Unity Catalog, SQL Warehouses, DBFS, Jobs, and other
                       services via REST APIs

The design goal is stated explicitly: Databricks credentials never reach the client, authentication boundaries are clear, and each layer scales independently.

The load-bearing word there is "all." Every Databricks call is proxied through your backend. It sounds obvious written down, and it is the first thing that gets violated when someone wants a fast dashboard and calls the SQL Warehouse straight from the browser with a token in local storage. If you take one structural rule from the Built-On track, take that one.

Layer 4 is the one people under-plan. You need somewhere to store users, organizations, and encrypted customer credentials, which means you are running an application database alongside Databricks and inheriting all the key-management responsibility that comes with storing customer credentials at rest.

07How to choose a Databricks deployment model

This is the decision the rest of your architecture hangs off. Databricks documents four models.

The framework gives five selection criteria, and they are good questions in the order they are asked:

1. Data residency. Does the customer's data need to stay in their environment?
2. Operational capacity. Do you want to manage infrastructure, or does the customer prefer to?
3. Customer sophistication. Does the customer have a platform team capable of managing Databricks?
4. Regulatory constraints. Do compliance requirements dictate where data can reside?
5. Scale and economics. Which model gives you the best unit economics?

Databricks also notes that many partners offer more than one model, typically Partner Hosted for customers who want simplicity and Hybrid for enterprise customers with data residency or compliance requirements. Treat the models as a product-line decision, not a one-time architectural choice.

Side Car deserves a closer look because it is the least familiar of the four. Partners build and govern assets centrally, then deliver them into customer environments via OpenSharing and Clean Rooms, keeping control of asset quality, versioning, and IP while the customer keeps authority over their data and execution environment. Customers can consume shared datasets from non-Databricks systems and run compute wherever they like, while Databricks centralizes policy enforcement and asset governance. If your value is the asset rather than the application, this is the model to read twice.

08The deployment model trap: Customer Managed limits your program benefits

Here is the sentence I mentioned at the top. On the Customer Managed page, Databricks states:

Due to limitations in telemetry and application management, program benefits are limited for Customer Managed deployments.

Sit with that for a second, because it connects two things that look unrelated.

The Measurement and Attribution pillar exists so Databricks can observe adoption and attribute joint impact to you. Customer Managed means the customer owns the workspace, the infrastructure, and the runtime. You ship notebooks, Databricks Asset Bundles, Terraform modules, or Python packages, and then you are not in the execution path. There is no product of yours making tagged API calls, because the customer's own workspace is making them.

So the model with the lowest operational burden for you is also the model where attribution is weakest, and attribution is what partner benefits are built on. That is not a hidden penalty, it is a structural consequence, and Databricks documents it.

Now consider what most consulting-built solution accelerators look like. A repo of notebooks, a job definition, a config file, a deployment guide. The customer clones it and runs it in their workspace. That is Customer Managed, by default, without anyone having chosen it.

If you are building an accelerator and you want program benefits, you have three honest options:

• Accept the tradeoff. Build Customer Managed because it fits the buyer, and treat the accelerator as a services differentiator and credibility asset rather than a route to partner benefits.
• Move up a model. Wrap the same logic in a Partner Hosted or Hybrid application so there is a product in the execution path that can carry a User-Agent and be managed and versioned by you.
• Go Side Car. If the output is a governed asset (a metric view, a curated dataset, a model), deliver it via OpenSharing so you keep central control of quality and versioning while the customer keeps their data.

What you should not do is build Customer Managed by accident and then be surprised when the attribution story is thin. I would have made a different architectural choice at the start if I had read that page before designing rather than during.

09Firefly Analytics: read the reference implementation, not just the prose

The single most useful resource attached to the PWAF is Firefly Analytics, an open-source SaaS application published by Databricks Labs specifically as a PWAF reference implementation. Source is at github.com/databrickslabs/firefly, it runs live at firefly-analytics.com, and the architecture docs are at firefly-analytics.com/docs.

Its stack is documented rather than implied:

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS, shadcn/ui, TanStack Query
• Backend: Next.js API routes, PostgreSQL with Drizzle ORM, Better-Auth
• Databricks: Unity Catalog, SQL Warehouses, DBFS, Volumes, Databricks Apps
• Deployment: Vercel for the frontend, Docker, VM, or serverless for the proxy

The patterns it demonstrates map one-to-one onto the framework's abstract guidance: SSO-SPN authentication, Databricks identity handling, workspace-catalog binding for tenant isolation, application-tier auto-scaling, hybrid tenancy, and organization and user onboarding. It also demonstrates six things Built-On partners commonly build, including embedded Databricks Apps via a proxy, notebook and code and SQL editors, a data catalog, and a pipeline editor.

Two ways to use it that are better than reading it start to finish:

As a diff target. Pick the one pattern you are least sure about, credential isolation between tenants, say, and read only Firefly's implementation of it. Compare against yours. The gap is your work item.

As AI context. The framework explicitly suggests pointing AI tools at Firefly's source, which carries inline comments explaining PWAF principles in context. Combined with the llms.txt and ai-context.txt files, you can ask concrete questions ("how does Firefly bind an organization to a catalog?") and get answers grounded in working code instead of paraphrased docs.

Do not deploy it as your product. It is a reference implementation provided for learning, with no support commitment beyond documentation and your Databricks partner team.

10Field notes: mapping a real accelerator onto the PWAF

Abstract frameworks get concrete when you run something through them. Here is the accelerator I built at WorldLink Labs, the Semantic Model Migration Accelerator, described the way the PWAF would want it described.

What it does. Converts Power BI semantic models exported as TMDL into governed Unity Catalog metric views, with deterministic DAX-to-SQL translation, flagged-measure review bundles, and KPI parity validation against the Power BI baseline.

The pipeline. Five stages: parse .tmdl files for tables, measures, relationships, and partition sources; translate using configurable DAX-to-SQL, format string, and relationship mapping rules; generate metric view YAML plus model summaries and review bundles; deploy by registering metric views as Unity Catalog objects through the SQL Statement Execution API; validate by comparing KPI results against the Power BI baseline and producing reviewer-ready quality reports.

The numbers. A moderately complex model takes an engineer 2 to 3 days by hand. Automated conversion runs in under 2 minutes per model. Conservative time savings are 60 to 80 percent versus manual conversion, with internal benchmarks reaching over 95 percent on supported star-schema models. The repo carries 156+ automated tests passing in CI, 23 sample TMDL packs across topologies, and a reference workload migrating 12 measures.

Now the honest PWAF mapping, pillar by pillar.

Two things I would keep exactly as they are.

The explicit non-goals. The accelerator documents what requires additional scope as loudly as what works: Power BI Import-mode models (data must be materialized as Delta first), calculation groups and many-to-many relationships (roadmap), row-level security (reapplied directly in Unity Catalog), and composite models (only DirectQuery portions migrate automatically). Naming the boundary is a credibility feature. Reviewers and customers both trust a scoped tool more than a tool that claims everything.

Determinism as the supported path. Optional, bounded Mosaic AI review handles edge cases, but the production path stays deterministic. For a migration tool where the deliverable is numerical parity with an existing report, "the LLM will figure it out" is not a validation story. Parity is measurable, and a >95 percent parity target is a claim you can be held to.

The thing I got wrong was upstream of all of this: I designed a genuinely good Customer Managed solution without registering that Customer Managed is where program benefits are thinnest. The architecture was not the problem. The model selection was made implicitly by the delivery format.

11How to get started with the PWAF

In the order that avoids rework:

1. Join the Databricks Partner Program. The framework is public, but co-sell, go-to-market benefits, and validation submissions require active membership via the Partner Portal.
2. Take the ISV PWAF training. It is short, and it gives you the vocabulary and the resource map. The knowledge check needs 80 percent or higher.
3. Identify your track. Connected ISV, Data Collaboration, or Built-On. Read your track's requirements page in full before designing anything.
4. Choose your deployment model explicitly, and write down why. Use the five criteria. Record the decision with its tradeoffs, including the Customer Managed benefits limitation if that is where you land.
5. Implement the hard requirements first. OAuth, Unity Catalog registration, and the programmatic User-Agent. These are cheap now and expensive later.
6. Verify attribution with a query, not a hope. Run the system.access.audit check above and confirm your User-Agent shows up.
7. Read Firefly for the pattern you are least sure about. Diff its implementation against yours.
8. Write the customer connection documentation. Prerequisites, required Databricks privileges, supported auth types, step-by-step setup per auth type.
9. Produce the pillar-4 artifacts. Runbook, support boundary, versioning scheme, upgrade path, breaking-change notes.
10. Ask for architectural review before you submit. Partner Engineering takes technical questions through a Partner Support request in the Partner Portal. Use that earlier than feels necessary.

12PWAF best practices, and the mistakes that cost the most

Choose the deployment model before the tech stack. It determines your attribution ceiling, your operational burden, and which program benefits are even available. Deciding it implicitly through delivery format is the single most expensive mistake in this whole process.

Treat technical standards as acceptance criteria. OAuth, Unity Catalog, User-Agent, Genie attribution, MCP for agents. Put them in your definition of done, not your backlog.

Instrument attribution on day one. It is one string in your connection code path. Retrofitting it across every driver, SDK call, job, and CLI invocation later is tedious and easy to do incompletely.

Do not let customers configure your telemetry. The framework prohibits it, and even if it did not, customer-configured telemetry is telemetry you do not have.

Define the ideal customer profile and the explicit non-goals. A tool that says "star-schema models with SUM, DISTINCTCOUNT, DIVIDE, AVERAGEX, and time intelligence" is more trustworthy than one that says "any semantic model."

Make quality measurable. Parity percentages, test counts, benchmark workloads. "Significantly faster" is not a claim; "under 2 minutes per model versus 2 to 3 days manually" is.

Write the docs before the demo. Documenting required privileges first prevents you from quietly building on an over-privileged service principal.

Build a demo that works on someone else's data. Bundled reference workloads and multiple sample topologies exist for exactly this reason. A demo that only runs on your dataset is a video, not a solution.

Keep AI on the optional path when correctness is the deliverable. Deterministic core, bounded AI assist for edge cases, clearly labelled. This is easier to validate and easier to defend.

Plan for schema evolution if you share data. A shared table is an API contract, and CDF plus backward compatibility planning is how you avoid breaking consumers.

13Sources

Everything in this post is drawn from the official framework. If you only open three of these, make them the integration requirements, the deployment models overview, and the Customer Managed page.

14Related reading

If you want the platform context these partner patterns sit on top of, my breakdown of Databricks Data + AI Summit 2026 covers Genie, Unity Catalog semantics, and metric views in depth, which is most of what the PWAF assumes you already understand.

If you are building an accelerator right now, do one thing before you write more code: open the deployment models page, pick your model deliberately, and write down the tradeoff you are accepting. That paragraph is worth more than the next week of implementation.