databricks-app

Databricks App Architecture — Alpura

Apply to every Databricks App. The workspace instructions are authoritative if another example conflicts with this skill.

Required architecture

my-app/
├── app.py              # orchestration, configuration, layout wiring, callbacks
├── data.py             # WorkspaceClient Statement Execution reads only
├── logic.py            # pandas transformations and business rules only
├── ui.py               # Plotly figures and Dash/Streamlit components only
├── _logger.py          # shared structured logger
├── app.yaml            # command and resource-backed environment variables
├── requirements.txt
└── APP.md              # purpose, audience, Gold tables, filters, KPIs, acceptance criteria

Rules

• No Spark session exists in Databricks Apps.
• data.py uses WorkspaceClient().statement_execution and follows @data-access.
• logic.py has no SQL and no UI imports.
• ui.py has no SQL, remote access, KPI definitions, or aggregations.
• app.py owns validated configuration and orchestration; it contains no SQL.
• UI-facing reads are Gold-only and use three-part Unity Catalog names.
• Reuse centrally defined semantic KPIs; never recalculate them in an app.
• Import get_logger from _logger.py in every Python module; never use print().
• Catch and translate exceptions at every layer boundary. Never show raw tracebacks.
• Every visual UI supports alpura-dark and alpura-light from @ui-ux-patterns.

Configuration pattern

All values vary by environment and must come from app resources or environment variables. Validate them during startup without opening a remote connection.

"""Application entry point and orchestration."""
import os

from _logger import get_logger

logger = get_logger(__name__)

CONFIG = {
    "table_name": os.environ["UC_TABLE_NAME"],
    "warehouse_id": os.environ["DATABRICKS_WAREHOUSE_ID"],
    "row_limit": int(os.environ["APP_ROW_LIMIT"]),
}

logger.info("Config loaded")