# merchmix-assortment

A multi-tenant Rust backend for Merchmix Core assortment and range-planning data. The repository contains Axum-style authenticated handlers, SQLx database access, tenant-specific connection pools, database migrations for assortment and range-plan schemas, audit logging, and configurable business rules. The authoritative implementation evidence is limited in the supplied source excerpt; only custom-field listing is directly confirmed as an exposed operation.

## Business Summary

This service supports retail teams planning which products and product options should be included in an assortment or range. It also provides configurable custom fields so each retailer can store planning information specific to their business. The available evidence does not establish the full set of planning workflows implemented in this version.

## Capabilities

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Custom Field Configuration | Planning | `production` | `read` | user_facing, agent_facing |
| Assortment and Range Planning Data Management | Planning | `partial` | `write` | internal |
| Planning Audit Logging | Reporting | `partial` | `write` | internal |
| Planning Rule Configuration | Planning | `partial` | `write` | internal |

**Custom Field Configuration** — Lets a retailer retrieve the custom fields configured for its planning data.

**Assortment and Range Planning Data Management** — Provides database structures intended to support assortment and range-plan information used by retail merchandise planners.

**Planning Audit Logging** — Stores an audit trail for changes made to planning data.

**Planning Rule Configuration** — Supports persisted configuration for rules used by planning processes.

## Workflows

**Retrieve Tenant Custom Fields** — Returns the custom-field definitions belonging to the authenticated tenant and refreshes the local reference cache.

1. Authenticate the request with a bearer token.
2. Resolve the tenant and its database pool.
3. Query custom-field definitions from the tenant database.
4. Update the tenant reference cache with the returned definitions when the cache is available.
5. Return the definitions as JSON.

## Architecture

A Rust, multi-tenant web service organized around handlers, middleware, models, services, database queries, and SQL migrations. Requests use tenant and bearer-token middleware; handlers access tenant-scoped SQLx pools and may update in-process reference caches.

**Components:** Rust application runtime, Axum-style HTTP handlers using application state, Bearer-token authentication middleware, Tenant-resolution middleware, Tenant-scoped database pools, SQLx file-backed database queries, Reference-cache subsystem, Domain models, including custom-field definitions, SQL migration history for assortment, range plans, audit logs, and rule configurations, Containerized Azure deployment configuration

**Patterns:** Multi-tenancy through tenant context and tenant-specific database access, Middleware-based authentication and tenant resolution, Repository/query-file database access using SQLx, Process-local reference caching with database refresh on read, Database-first schema evolution through ordered migrations

## Interfaces

| Kind | Identifier | Description |
|---|---|---|
| `http` | `Custom-field listing handler` | Authenticated JSON operation implemented by `src/handlers/custom_field/list.rs`; the concrete HTTP route path is not present in the supplied evidence. |
| `other` | `SQL migrations` | Ordered migration files define and evolve the service's database schema, including assortment, range-plan, audit-log, and rule-configuration structures. |

## Data

| Entity | Ownership | Description |
|---|---|---|
| Custom field definitions | `owns` | Tenant-specific definitions identified by field keys and returned as `CustomFieldDefinition` records. |
| Assortment schema data | `owns` | Data structures created by the assortment-schema migration. The supplied evidence does not enumerate the contained tables or fields. |
| Range-plan data | `owns` | Data structures created or changed by the range-plan schema migrations. |
| Audit log records | `owns` | Persisted records supported by the dedicated audit-log migration. |
| Planning rule configurations | `owns` | Seeded rule configuration records used by planning functionality. |

## Dependencies

| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| PostgreSQL tenant databases | `database` | `reads` | `critical` |
| merchmix-forge-contracts | `internal_service` | `depends_on` | `required` |
| Bitbucket | `external_service` | `uses` | `supporting` |
| Azure Container Apps / Azure Container Registry | `other` | `uses` | `supporting` |
| Reference cache | `other` | `writes` | `optional` |

## Technology

Rust, Axum, SQLx, SQL, PostgreSQL, Bearer-token authentication, Docker, Azure Container Apps, Azure Container Registry, Bitbucket Pipelines

## Limitations

- Only one authoritative source file was supplied in detail, so the complete HTTP route inventory and service behavior cannot be established.
- The concrete URL path, HTTP method, request headers beyond bearer authentication, and response contract for custom-field listing are not shown.
- The migration names confirm assortment, range-plan, audit-log, and rule-configuration persistence, but do not prove the corresponding user-facing workflows are fully implemented.
- No screens or frontend routes are evidenced in the supplied repository signals.
- No queue, webhook, ERP, forecasting, allocation, replenishment, markdown, buying, or OTB integration is confirmed by the available evidence.
- The exact database engine configuration is inferred from the handler comment and SQLx usage; connection and deployment configuration was not provided in full.
- The repository listing includes tenant and credential-related configuration filenames, but no secret values are described or included here.

## Agent Instructions

Use this repository primarily for tenant-scoped assortment and range-planning persistence and custom-field configuration. Treat custom-field retrieval as the only directly confirmed exposed operation.

- Authenticate requests with the repository's bearer-token middleware and resolve the tenant before accessing planning data.
- For custom-field definitions, use the database-backed listing behavior rather than assuming the process-local reference cache is authoritative.
- Do not assume a route path from the handler filename; obtain the router registration or OpenAPI definition before constructing an HTTP call.
- Treat assortment, range-plan, audit-log, and rule-configuration capabilities as partial until their handlers and services are inspected.
- Do not route requests for allocation, replenishment, markdown, forecasting, ERP exchange, or OTB workflows here without additional implementation evidence.
- Keep tenant data isolated by using the tenant-scoped pool and tenant context supplied by middleware.

## Source

| Field | Value |
|---|---|
| Repository | `merchmix-assortment` |
| Branch | `master` |
| Commit | `7c3f5f3a843b` |
| Generated by | `gpt-5.6-luna` |

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