Repository Map

`apps/`

Deployable applications, each with its own lifecycle:

mx_fuels_reporting_app/ — the primary product. apps/web/ is the live Next.js (T3 Stack) dashboard, deployed via compose.js.yaml. See Apps → MX Fuels Reporting App. The legacy pre-Next.js-pivot Streamlit frontend + GraphQL/FastAPI backend (apps/{backend,client,frontend}) and their compose.yaml / compose.py.yaml have been deleted from the repository.
financial-flows/ — see Apps → Financial Flows.

`packages/`

Shared, versioned Python packages, workspace members of the root pyproject.toml:

utils — cross-cutting config/settings, Azure Key Vault access, caching, system helpers
vcl — the Visory Command Line, used to scaffold new projects/apps
db — shared database access layer

`orchestration/`

The Astronomer/Airflow project: DAGs (orchestration/dags/), dbt/Cosmos integration (see the manual-review flag in AI Experts), and database includes (orchestration/include/db/, migrations). Has its own uv.lock and vendors utils/vcl as pre-built wheels rather than joining the root UV workspace. See Orchestration.

`projects/`

Data science / analytics projects, DVC-versioned, workspace members of the root pyproject.toml (except 2025_permit_ratification, explicitly excluded). See Projects for the full list and per-project detail.

`scripts/`

Workspace bootstrapping and scaffolding:

workspace-setup/00-setup.sh → 07-astronomer.sh — ordered provisioning steps run by Devbox (venv, Homebrew, uv tool, Jupyter kernel, git config, symlinks, Astronomer CLI)
project-init.sh — scaffolds a new projects/<name> (UV lib + DVC init)
app-init.sh — scaffolds a new apps/<name> (standalone UV app, no workspace)
environ/export_settings.py — the secret-export script used by .envrc (see Onboarding → Environment & Secrets)

`templates/`

Scaffolding templates consumed by project-init.sh / app-init.sh (e.g. templates/.envrc) and doc kickoff templates.

`docs/`

This Astro/Starlight documentation site.

`web/site/`

A separate T3 Stack site, live and actively maintained (last touched 2026-07-14, same as the dashboard). Its relationship to apps/ scope is still to be finalized with the team — treat as active code, not legacy, until confirmed otherwise.