AR Service (ar-app)

Relevant source files

The following files were used as context for generating this wiki page:

• apps/ar-app/src/ar/ar.service.ts
• apps/ar-app/src/ar/ar.module.ts
• apps/ar-app/src/ar-app.module.ts
• libs/shared/types/ar.types.ts
• apps/ar-app/src/ar/ar.service.spec.ts
• apps/ar-app/test/ar.e2e-spec.ts
• apps/ar-app/src/ar/ar.controller.spec.ts
• deploys/README.md

The ar-app is a dedicated microservice within the e-commerce platform responsible for managing Augmented Reality (AR) snapshots. Its primary function is to store and retrieve images captured by users, presumably while using an AR "try-on" feature with products. The service is designed to be a self-contained module that communicates with other parts of the system, such as the API Gateway, via a NATS message broker.

This service handles the persistence of AR snapshot data, including references to the user and product, the image URL, and any associated metadata. It provides a simple, paginated query interface for retrieving these snapshots.

Sources: README.md, apps/ar-app/src/ar/ar.service.ts

Architecture and Components

The ar-app is built using the NestJS framework and follows a standard modular architecture. It is part of a larger monorepo structure, as indicated by the nest-cli.json configuration. The core logic is encapsulated within the ArModule.

Sources: nest-cli.json:15-22, apps/ar-app/src/ar-app.module.ts

The diagram below illustrates the key components and their dependencies within the ar-app.

This diagram shows the main application module ArAppModule importing the feature module ArModule.

Sources: apps/ar-app/src/ar-app.module.ts, apps/ar-app/src/ar/ar.module.ts

Key Components

Component	Description	Source File
ArController	Handles incoming NATS messages for AR-related events. It delegates business logic to the ArService.	apps/ar-app/src/ar/ar.controller.spec.ts
ArService	Contains the core business logic for creating and listing AR snapshots. It interacts with the database via PrismaService.	apps/ar-app/src/ar/ar.service.ts
PrismaService	A service that provides an instance of the Prisma Client, used for all database operations related to the ARSnapshot model.	apps/ar-app/src/ar/ar.module.ts:6

Data Model: ARSnapshot

The service manages a single data entity: ARSnapshot. This model stores information about each AR image captured by a user. While the schema.prisma file was not provided, its structure can be inferred from the service's interaction with the Prisma client and the defined response types.

Sources: apps/ar-app/src/ar/ar.service.ts:28-34, libs/shared/types/ar.types.ts:9-16

The following Entity-Relationship diagram represents the inferred ARSnapshot model.

ARSnapshot Fields

Field	Type	Constraints	Description
id	String	Primary Key	Unique identifier for the snapshot.
userId	String	Nullable	The ID of the user who created the snapshot. Can be null for anonymous users.
productId	String	Required	The ID of the product associated with the snapshot.
imageUrl	String	Required	The URL of the stored snapshot image.
metadata	Json	Nullable	A JSON object to store extra data like camera position, lighting, etc.
createdAt	DateTime	Required	Timestamp when the snapshot was created.

Sources: apps/ar-app/src/ar/ar.service.spec.ts:31-38, libs/shared/types/ar.types.ts:9-16

NATS API

The ar-app exposes its functionality over NATS. Other services can communicate with it by sending messages to specific event patterns.

Sources: apps/ar-app/test/ar.e2e-spec.ts:11,70,111

NATS Endpoints

Event Pattern	Payload DTO	Response Type	Description
EVENTS.AR.SNAPSHOT_CREATE	ARSnapshotCreateDto	ARSnapshotCreateResponse	Creates a new AR snapshot record in the database.
EVENTS.AR.SNAPSHOT_LIST	ARSnapshotListDto	PaginatedARSnapshotsResponse	Lists existing AR snapshots with filtering and pagination.

Sources: apps/ar-app/test/ar.e2e-spec.ts, apps/ar-app/src/ar/ar.service.ts

Sequence Diagram: Create Snapshot

The following diagram shows the sequence of events when a client (e.g., API Gateway) requests the creation of a new AR snapshot.

This flow demonstrates the request-response pattern used for creating a snapshot via NATS.

Sources: apps/ar-app/test/ar.e2e-spec.ts:70-76, apps/ar-app/src/ar/ar.controller.spec.ts:40-56, apps/ar-app/src/ar/ar.service.ts:22-40

Core Functionality

Snapshot Creation

The snapshotCreate method in ArService is responsible for creating a new ARSnapshot record.

This flowchart shows the logic for creating an AR snapshot, including error handling.

Sources: apps/ar-app/src/ar/ar.service.ts:22-40, apps/ar-app/src/ar/ar.service.spec.ts:80-97

The method accepts a DTO with the following optional and required fields:

• productId (required)
• imageUrl (required)
• userId (optional)
• metadata (optional)

If the database operation fails, the service catches the error and throws a ValidationRpcException to ensure a consistent error format is sent back to the caller over NATS.

Sources: apps/ar-app/src/ar/ar.service.ts:36-39

Snapshot Listing

The snapshotList method provides a paginated and filterable list of ARSnapshot records.

This flowchart details the process of listing snapshots, including filtering, pagination, and parallel database queries for efficiency.

Sources: apps/ar-app/src/ar/ar.service.ts:42-77, apps/ar-app/src/ar/ar.service.spec.ts:182-195

Key features of the listing functionality:

• Filtering: Supports filtering by userId and/or productId.
• Pagination: Uses page and pageSize to return a subset of results. Defaults are page: 1 and pageSize: 20.
• Efficiency: It runs findMany (to get the items for the page) and count (to get the total number of items) in parallel using Promise.all.
• Sorting: Results are ordered by createdAt in descending order.

Sources: apps/ar-app/src/ar/ar.service.ts:51-68

Configuration and Deployment

The ar-app requires the following environment variables for its operation:

Variable	Description	Example
NATS_URL	The connection URL for the NATS message broker.	nats://nats-server-ip:4222
DATABASE_URL_AR	The connection string for the PostgreSQL database dedicated to the AR service.	postgresql://postgres:password@db-server:5432/ar_db

Sources: deploys/README.md

The service is containerized using Docker and is intended for deployment as part of a larger microservices architecture managed by Docker Compose.

Sources: docker/README.md

Testing

The ar-app includes a comprehensive suite of tests:

• Unit Tests (*.spec.ts): These tests isolate individual components like ArService and ArController. Dependencies such as PrismaService are mocked to ensure tests are fast and predictable.
• End-to-End Tests (*.e2e-spec.ts): These tests verify the behavior of the entire microservice. They set up a live NATS connection and interact with the service using a NATS client, validating the flow from message receipt to database interaction and response. The database is cleaned before each test run to ensure isolation.

Sources: apps/ar-app/src/ar/ar.service.spec.ts, apps/ar-app/src/ar/ar.controller.spec.ts, apps/ar-app/test/ar.e2e-spec.ts

Summary

The AR Service (ar-app) is a focused and well-defined microservice for managing AR snapshots. It follows standard NestJS patterns, uses Prisma for database access, and communicates asynchronously via NATS. Its simple API for creating and listing snapshots, combined with a clear data model and comprehensive tests, makes it a reliable component for handling user-generated AR content within the application.