# azuredomains

Azuredomains is an internal infrastructure operations dashboard for MerchMix. A FastAPI backend manages a service/domain manifest in PostgreSQL and collects read-only operational data from Azure Container Apps, Container App Jobs, Azure Logic Apps, Azure Key Vault, Databricks, and GCP Cloud Scheduler. A Next.js frontend presents service environments, Azure fleet capacity and cost estimates, job execution health, and multi-phase data-pipeline status.

## Business Summary

This tool gives MerchMix operations teams one place to see which applications and domains exist, whether they are live, how Azure applications and jobs are running, what they may cost, and whether the retail data pipelines are progressing through their scheduled stages. Users can maintain the service register and trigger fresh infrastructure or pipeline checks.

## Capabilities

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Service Manifest Management | Other | `production` | `write` | user_facing, agent_facing |
| Service Manifest Deletion | Other | `production` | `destructive` | user_facing, agent_facing |
| Azure Environment Inventory | Other | `production` | `execute` | user_facing, agent_facing, internal |
| Azure Infrastructure Monitoring | Reporting | `production` | `read` | user_facing, agent_facing |
| Azure Infrastructure Refresh | Reporting | `production` | `execute` | user_facing, agent_facing |
| Data Pipeline Monitoring | Reporting | `production` | `read` | user_facing, agent_facing |
| Data Pipeline Refresh | Reporting | `production` | `execute` | user_facing, agent_facing |
| Dashboard Access Gate | Authentication | `partial` | `execute` | user_facing |

**Service Manifest Management** — Maintain the register of MerchMix applications, their repositories, branches, domains, deployment status, and development and live environment configuration.

**Service Manifest Deletion** — Remove an application from the service and domain register.

**Azure Environment Inventory** — Inspect deployed application environment configuration and import the current environment details into the service register.

**Azure Infrastructure Monitoring** — Monitor Azure Container Apps and Jobs, including running replicas, scaling limits, execution outcomes, resource usage, operational risks, and estimated monthly cost.

**Azure Infrastructure Refresh** — Request a fresh Azure infrastructure snapshot instead of using the in-process cached result.

**Data Pipeline Monitoring** — Track the health and schedule of the bstore and blueillusion retail data pipelines across source synchronization, transformation, cloud synchronization, and WSSI cube-building stages.

**Data Pipeline Refresh** — Fetch the latest available statuses and schedules for the monitored data pipelines.

**Dashboard Access Gate** — Require users of the web interface to sign in before viewing the infrastructure dashboard.

## Workflows

**Maintain service manifest** — An operator reviews and updates the central application and domain register.

1. Open the Forge infrastructure dashboard and pass the client-side sign-in gate.
2. Open the Service manifest view.
3. Search or filter existing application records.
4. Create or edit repository, branch, domain, status, and environment fields.
5. Submit the record, which upserts the service by application name.
6. Optionally remove a service or refresh its Azure environment data.

**Review Azure estate** — An operator assesses Azure application and job health and estimated spend.

1. Open the Container Apps or Jobs view.
2. Load the cached fleet snapshot.
3. Review replicas, scaling capacity, resource sizes, estimated costs, failures, and risk summaries.
4. Trigger a fleet refresh when current Azure data is required.
5. Use filters and sorting to investigate individual resource groups, applications, or jobs.

**Investigate retail data pipelines** — An operator checks whether the monitored brand pipelines are progressing through their scheduled stages.

1. Open the Data pipelines view.
2. Review each pipeline and its phases.
3. Inspect source sync, dbt/Databricks transformation, cloud sync, and WSSI cube-build status and schedules.
4. Trigger a live pipeline refresh when the displayed snapshot is stale.
5. Use last-run, next-run, paused, missing, and failure indicators to identify issues.

## Architecture

A single-container deployment combines a statically exported Next.js frontend with a FastAPI application server. FastAPI serves the exported frontend assets, exposes JSON APIs, persists the service manifest in PostgreSQL, and performs asynchronous read-only integrations with Azure and other cloud APIs.

**Components:** FastAPI application in `main.py` with health, service, fleet, and pipeline routes., PostgreSQL connection pool using asyncpg; startup creates and migrates the `services` table., Azure authentication and ARM/Key Vault environment inspection in `azure_env.py`., Azure Container App and Job inventory, retry, pacing, caching, and cost estimation in `fleet.py`., Cross-provider pipeline status aggregation in `pipelines.py`., Next.js App Router frontend with service, Container Apps, Jobs, and data-pipeline dashboard panels., Docker multi-stage build producing one Python container with exported frontend assets., Bitbucket pipeline building an image and deploying it to Azure Container Apps.

**Patterns:** Asynchronous FastAPI handlers and HTTP clients., Shared Azure credential and token cache across integration modules., Read-through in-process caching for fleet and likely pipeline snapshots., Explicit refresh endpoints for bypassing cached operational data., Database schema initialization and additive column migration during application startup., Next.js same-origin `/api` proxy in development and static export in production.

## Interfaces

| Kind | Identifier | Description |
|---|---|---|
| `http` | `GET /health` | Returns a basic service health response. |
| `http` | `GET /api/services` | Lists service manifest records ordered by application name. |
| `http` | `POST /api/services` | Creates or updates a service manifest record using the application name as the key. |
| `http` | `DELETE /api/services/{app_name}` | Deletes a service manifest record. |
| `http` | `POST /api/services/{app_name}/refresh` | Refreshes environment information for one application from Azure. |
| `http` | `POST /api/services/refresh-all` | Refreshes environment information for all applicable services from Azure. |
| `http` | `GET /api/fleet` | Returns cached or computed Azure Container App and Job fleet data, including status, replicas, executions, risks, and estimated costs. |
| `http` | `POST /api/fleet/refresh` | Performs a fresh Azure fleet read and returns the resulting data. |
| `http` | `GET /api/pipelines` | Returns monitored data-pipeline phases, schedules, and run status. |
| `http` | `POST /api/pipelines/refresh` | Performs a fresh multi-provider pipeline status read. |
| `other` | `Static web application at /` | Next.js dashboard with a client-side sign-in page and four operational views: Service manifest, Container Apps, Jobs, and Data pipelines. |

## Screens

| Route | Name | Purpose |
|---|---|---|
| `/` | Sign in | Client-side access gate for the infrastructure workspace. |
| `/` | Service manifest | View, search, filter, create, edit, delete, and refresh application domain and environment records. |
| `/` | Container Apps | Review Azure Container App status, replica capacity, resource usage, cost estimates, and scaling risk. |
| `/` | Jobs | Review Azure job triggers, execution history, failures, durations, and estimated cost. |
| `/` | Data pipelines | Review bstore and blueillusion pipeline phases, schedules, last runs, next runs, and status. |

## Data

| Entity | Ownership | Description |
|---|---|---|
| Service manifest record | `owns` | Application name, repository, branch, domain, deployment status, live environment content, development environment content, and update timestamp. |
| Azure Container App inventory | `reads` | Container App name, resource group, running status, current/minimum/maximum replicas, CPU, memory, estimated monthly cost, maximum possible cost, and cost gap. |
| Azure Container Job inventory | `reads` | Job name, resource group, trigger type, resource sizing, execution counts and outcomes, average duration, estimated monthly executions and cost, and last status. |
| Pipeline definition and phase status | `reads` | Retail pipeline labels, phases, phase types, schedules, presence or paused state, last and next runs, provider-specific details, and summaries. |
| Azure environment configuration | `reads` | Resolved deployed environment variables or dotenv content obtained from Container App configuration and Azure Key Vault references. |

## Dependencies

| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| PostgreSQL | `database` | `writes` | `critical` |
| Azure Resource Manager | `external_service` | `reads` | `critical` |
| Azure Key Vault | `external_service` | `reads` | `required` |
| Azure Identity / DefaultAzureCredential | `library` | `authenticates_through` | `critical` |
| Azure Logic Apps | `external_service` | `reads` | `required` |
| Azure Container App Jobs | `external_service` | `reads` | `required` |
| Azure Databricks Jobs API | `external_service` | `reads` | `required` |
| Google Cloud Scheduler | `external_service` | `reads` | `optional` |
| Azure Container Apps deployment | `internal_service` | `depends_on` | `supporting` |
| Next.js | `library` | `uses` | `critical` |

## Technology

Python 3.12, FastAPI 0.115, Uvicorn, asyncpg, PostgreSQL, httpx, aiohttp, azure-identity, Next.js 16, React 19, TypeScript, Tailwind CSS, Radix UI, Docker, Azure Container Apps, Bitbucket Pipelines

## Limitations

- This repository is an infrastructure operations dashboard, not a retail merchandise-planning engine; no implementation of WSSI calculations, OTB, range planning, size curves, markdowns, allocation, replenishment, buying, or assortment planning was found.
- The supplied `main.py`, `azure_env.py`, `fleet.py`, and `pipelines.py` excerpts are truncated, so exact response schemas, validation rules, refresh update behavior, and some route implementations cannot be fully established.
- The service manifest is persisted in PostgreSQL, but the scanner also reports BigQuery, Databricks, and SQL-migration signals; this repository does not appear to own those analytical or pipeline stores.
- Fleet costs are approximate Azure Consumption-plan estimates based on configured CPU, memory, replicas, and execution history, not billing-system actuals.
- One blueillusion pipeline phase is deliberately static because its GCP Cloud Scheduler source of truth is not reachable from this application.
- The login is a client-side static credential check and backend route authentication was not evidenced; it should not be treated as a robust security boundary.
- Environment refresh can display or persist resolved environment configuration. Agents should treat these fields as potentially sensitive and never expose or copy them unnecessarily.
- No evidence establishes automated pipeline triggering, Azure resource mutation, deployment orchestration, or user/role management; refresh operations are described as read-only against external providers.

## Agent Instructions

Use this repository for MerchMix infrastructure inventory, service-register maintenance, Azure estate monitoring, and data-pipeline observability—not for merchandise-planning calculations or transactional retail operations.

- For service-register questions, use `GET /api/services`; use `POST /api/services` for an upsert and preserve the application-name key.
- Treat DELETE service operations as destructive and confirm the target application before executing.
- Use fleet GET endpoints for cached observations and the corresponding POST refresh endpoint when freshness is explicitly required.
- Use pipeline GET for status inspection and POST refresh for a live multi-provider read; do not claim that refresh starts or repairs a pipeline.
- Require the configured Azure subscription and appropriate cloud credentials before invoking Azure-backed refreshes.
- Do not reveal environment-variable contents, Key Vault values, Databricks client secrets, service-account material, or login credentials.
- Treat cost figures as estimates and distinguish current replicas from maximum possible capacity.
- Remember that frontend sign-in does not prove API authorization; independently verify deployment access controls before exposing these APIs.
- When routing a request about WSSI, OTB, range planning, allocation, replenishment, markdowns, or assortment decisions, route to a repository that implements those business capabilities instead.

## Source

| Field | Value |
|---|---|
| Repository | `azuredomains` |
| Branch | `main` |
| Commit | `691108265b34` |
| Generated by | `gpt-5.6-luna` |

*Generated by the Merchmix Skills Platform from the current codebase.*