# merchmix-beacon-beacon-api

merchmix-beacon-beacon-api is a Rust backend for the Merchmix Beacon product. It contains authentication, administrative, support, finance, and insights handlers, plus protobuf definitions for Beacon identity, finance, insights, and logistics APIs. The repository also includes document-store code and Azure infrastructure for deploying the service and its supporting resources.

## Business Summary

Beacon provides backend services for retailer operations and reporting. It appears to support identity and access, finance-related information, business insights, logistics information, and administrative or support workflows. The available evidence does not establish the exact retailer-facing workflows or calculations implemented by each API.

## Capabilities

| Capability | Category | Status | Access | Exposure |
|---|---|---|---|---|
| Identity and Access Management | Authentication | `partial` | `execute` | agent_facing, internal |
| Financial Information Management | Reporting | `partial` | `read` | agent_facing, internal |
| Business Insights | Reporting | `partial` | `read` | agent_facing, internal |
| Logistics Information Services | Logistics | `partial` | `read` | agent_facing, internal |
| Administrative Operations | Other | `partial` | `execute` | internal |
| Support Operations | Other | `partial` | `execute` | internal |
| Document Storage | Other | `partial` | `write` | internal |

**Identity and Access Management** — Provides Beacon's authentication and identity-related backend services so users or connected systems can access Beacon functionality.

**Financial Information Management** — Supports Beacon functionality involving finance-related information for retail operations.

**Business Insights** — Provides access to business insight information used to understand Beacon-managed retail activity.

**Logistics Information Services** — Supports Beacon's logistics-related information and integrations for retail operations.

**Administrative Operations** — Provides backend operations for administering the Beacon service.

**Support Operations** — Provides backend functionality for Beacon support staff or support workflows.

**Document Storage** — Stores and retrieves Beacon application documents used by the service.

## Workflows

**Authenticate Beacon access** — A user or connected client is authenticated before accessing Beacon services.

1. A client submits an identity or authentication request.
2. Rust authentication logic processes the request.
3. The service authorizes access to Beacon operations.

**Serve domain API requests** — Beacon handlers process requests for finance, insights, administrative, or support functions.

1. A client connects through one of the repository's API contracts or handlers.
2. The relevant Rust handler processes the request.
3. The service reads or writes Beacon documents or supporting resources as required.

## Architecture

A Rust service organized around handler modules, authentication, document persistence, domain document types, and protobuf API contracts. Azure infrastructure definitions and deployment files are included in the repository.

**Components:** Rust application entry point in src/main.rs, Authentication implementation in src/auth.rs and src/auth_handlers.rs, Domain handlers for administration, finance, insights, and support, Document models and document-store abstraction, Protocol buffer contracts for identity, finance, insights, and logistics, Azure Bicep infrastructure and deployment configuration, SQL bootstrap script under infra/bootstrap-databases.sql

**Patterns:** Protocol Buffers API contracts, Handler-based request processing, Document-store persistence abstraction, Infrastructure as code with Azure Bicep, Container-oriented deployment indicated by Dockerfile and Azure Container Registry infrastructure

## Interfaces

| Kind | Identifier | Description |
|---|---|---|
| `grpc` | `merchmix.beacon.identity.v1` | Protocol buffer contract for Beacon identity services. |
| `grpc` | `merchmix.beacon.finance.v1` | Protocol buffer contract for Beacon finance services. |
| `grpc` | `merchmix.beacon.insights.v1` | Protocol buffer contract for Beacon insights services. |
| `grpc` | `merchmix.beacon.logistics.v1` | Protocol buffer contract for Beacon logistics services. |
| `other` | `Rust handler modules` | Internal service handlers for administration, authentication, finance, insights, and support. The transport and route identifiers are not available in the supplied evidence. |

## Data

| Entity | Ownership | Description |
|---|---|---|
| Beacon documents | `owns` | Application documents represented by src/documents.rs and persisted through src/document_store.rs. |
| Identity data | `writes` | Identity-related data represented by the identity protobuf contract and authentication modules. |
| Finance data | `writes` | Finance-related API data represented by the finance protobuf contract and finance handlers. |
| Insights data | `reads` | Business insight data represented by the insights protobuf contract and insights handlers. |
| Logistics data | `reads` | Logistics-related API data represented by the logistics protobuf contract. |

## Dependencies

| Name | Kind | Relationship | Criticality |
|---|---|---|---|
| Azure deployment resources | `other` | `depends_on` | `required` |
| Azure Container Registry | `other` | `depends_on` | `required` |
| Azure Key Vault | `other` | `uses` | `required` |
| SQL database infrastructure | `database` | `depends_on` | `required` |
| Rust protobuf and service libraries | `library` | `uses` | `required` |

## Technology

Rust, Protocol Buffers, Likely gRPC service contracts, SQL, Docker, Azure Bicep, Azure Container Registry, Azure Key Vault, Bitbucket Pipelines, GitHub Actions

## Limitations

- The supplied scanner output does not include concrete route paths, RPC method names, request or response schemas, or authentication mechanisms.
- The existence of protobuf files supports API contracts, but does not by itself prove that every declared service is fully implemented or deployed.
- The exact database engine, connection behavior, document schema, and persistence ownership are not established.
- No evidence identifies retailer-facing screens or a web frontend in this repository.
- The evidence does not establish specific Merchmix planning capabilities such as WSSI, OTB, range planning, allocation, replenishment, or markdown optimization.
- Dependency names from Cargo.toml were not supplied, so external libraries and services cannot be enumerated reliably.

## Agent Instructions

Treat this repository as Beacon's Rust backend and API-contract repository, with identity, finance, insights, logistics, administration, support, and document-storage concerns.

- Use the protobuf files as the primary source for externally intended domain interfaces, but inspect their service and method definitions before constructing a request.
- Treat admin and support handlers as likely internal operations unless route or authorization evidence shows otherwise.
- Do not assume that the presence of a logistics or insights proto means the repository owns the underlying calculations or data.
- Inspect src/main.rs, handler registration, and build.rs to determine the actual transport, implemented services, and generated code before routing work here.
- Treat Azure infrastructure and SQL bootstrap files as deployment and dependency evidence, not as proof of business functionality.
- Do not infer WSSI, OTB, assortment planning, allocation, replenishment, or other planning capabilities without explicit implementation evidence.

## Source

| Field | Value |
|---|---|
| Repository | `merchmix-beacon-beacon-api` |
| Branch | `master` |
| Commit | `431dd8db927c` |
| Generated by | `gpt-5.6-luna` |

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