Skip to content
Visory LLC

Architecture Overview

This is a single monorepo (Visory-Analytics/pipelines) containing Python data pipelines, an Airflow orchestration project, and standalone web apps, tied together by a UV workspace for Python dependency resolution.

Top-level layout

Section titled “Top-level layout”
Directory Contains
apps/ Deployable applications with their own lifecycle (mx_fuels_reporting_app, financial-flows)
packages/ Shared, versioned Python packages consumed by projects/orchestration (db, utils, vcl)
orchestration/ Astronomer/Airflow project — DAGs, dbt/Cosmos, database includes, its own uv.lock
projects/ Data science / analytics projects, DVC-versioned
scripts/ Workspace bootstrapping and scaffolding (workspace-setup/, project-init.sh, app-init.sh)
templates/ Scaffolding templates for new apps/projects
docs/ This Astro/Starlight documentation site
web/site/ Visory’s Business website

App vs. Project vs. Package

Section titled “App vs. Project vs. Package”
  • Package (packages/*): a shared, importable Python library versioned independently (e.g. utils, vcl, db). Workspace members, referenced with { workspace = true } by anything that depends on them. orchestration/ instead vendors pre-built wheels of these packages since it has its own separate uv.lock.
  • Project (projects/*): a DVC-versioned data science / analytics deliverable — pipelines, notebooks, models. Scaffolded with scripts/project-init.sh, which runs uv init --lib . --project . and dvc init --subdir. Projects are UV workspace members ([tool.uv.workspace] members = ["packages/*", "projects/*"]) and can depend on utils/vcl/db directly.
  • App (apps/*): a standalone, deployable application with its own release lifecycle, scaffolded with scripts/app-init.sh (uv init --app . --no-workspace). Apps are not UV workspace members — they either bundle shared packages as wheels or vendor their own dependencies (e.g. apps/mx_fuels_reporting_app/apps/web is a self-contained Next.js app with no Python dependency at all).

UV workspace

Section titled “UV workspace”

The root pyproject.toml defines the workspace:

[tool.uv.workspace]
members = ["packages/*", "projects/*"]
exclude = ["projects/2025_permit_ratification"]


[tool.uv.sources]
vcl = { workspace = true }
utils = { workspace = true }
mx-com-reporting = { workspace = true }

orchestration/ deliberately sits outside this workspace — it resolves shared packages from pre-built wheels in orchestration/include/wheels/ instead, since the Airflow runtime has different dependency constraints than local dev.

Next

Section titled “Next”