Stella Catalog

Technical Product Specification v1

Document Status: Draft for Review Version: 1.0 Last Updated: March 2026 Previous product name: Astro Catalog (renamed to Stella Catalog)

Spec Precedence: Where this document conflicts with architecture_v3.md, the architecture document is the technical source of truth. This spec retains product scope, business requirements, and domain model authority. Sections marked ⚠️ SUPERSEDED have been replaced by architecture_v3.md and are kept for historical context only.

Executive Summary

Purpose

Stella Catalog is an open-source, AI-first, multi-tenant product information management (PIM) system designed to modernize how businesses manage, discover, and distribute product data. It serves as either a standalone headless catalog service or an "AI Sidecar" that enhances legacy PIM systems like PIMCore and Akeneo with semantic search and AI capabilities.

The canonical runtime is a standalone long-running NestJS process (self-hosted or containerised). A lightweight Vercel + Supabase deployment path is documented below for reference but is superseded by the standalone model defined in architecture_v3.md §15.

Key Benefits

Benefit	Description
AI-Native Search	Semantic search using vector embeddings enables natural language product discovery, going beyond keyword matching
Zero-Migration AI Upgrade	Active replication mode syncs with existing PIMs in real-time, adding AI capabilities without risky data migrations
Multi-Tenant SaaS Ready	Built-in tenant isolation via PostgreSQL Row-Level Security (RLS) enables secure multi-tenant deployments
Cloud-Ready	Deploy as a standalone NestJS process with any managed PostgreSQL (Supabase, RDS, etc.)
E-commerce Ready	Native validation schemas for Amazon, Shopify, and GS1 prevent syndication errors
Multi-Supplier Support	Manage offers from multiple suppliers, automatically match products, and select best offers
Reference Catalog Integration	Enrich products from industry catalogs (IceCat, Etilize, ETIM) with standardized data
AI Agent Compatible	MCP (Model Context Protocol) tools enable AI agents to search, compare, and quote products

Who Should Use Stella Catalog?

User Type	Use Case
B2B/B2C Retailers	Central product catalog with multi-supplier offer management and dynamic pricing
System Integrators	Add AI search to legacy PIMs without replacing existing infrastructure
E-commerce Platforms	Headless catalog backend with channel syndication validation
AI/LLM Developers	Product information backend for conversational commerce and AI agents
Distributors	Manage supplier catalogs, match products, and maintain canonical product records
Startups & SMBs	Simple containerised deployment with managed Postgres (e.g. Supabase, RDS)

Open Source License

Stella Catalog is released under an open-source license, enabling:

Self-hosted deployments with full control
Containerised deployment with any managed PostgreSQL
Community contributions and extensions
Transparent security auditing
No vendor lock-in

Vision & Core Principles
Target Use Cases
Technology Stack
Architecture Overview
Vercel + Supabase Deployment
Multi-Tenancy Model
Core Domain Model
AI & Discovery Layer
Integration & Replication
Multi-Supplier Product Management
Reference Catalog Integration
Catalog Sharing
CPQ & Pricing
Operational Features
Security
API Reference
Requirements Summary
Correctness Properties
Development Environment
Versioning & Lifecycle Management
Role & Permission Matrix
GraphQL Interface (Phase 2 Roadmap)
Embedding Cache Invalidation Strategy
Reference Catalog Prioritization
Enhanced Security Features
Updated Performance Targets
Extended CLI Commands

1. Vision & Core Principles

Vision

Stella Catalog is designed to be the AI-native product information backbone for modern commerce. It bridges the gap between legacy PIM systems and AI-powered discovery, enabling businesses to leverage semantic search, intelligent matching, and AI agent integration without abandoning existing investments. It can be deployed simply on Vercel + Supabase or self-hosted for full control.

Core Design Principles

API-First & Headless – All functionality exposed via well-defined REST APIs
AI-Native – Vector embeddings, semantic search, and MCP tools are first-class citizens
Sidecar-Ready – Designed to enhance existing PIMs via active replication, not replace them
Multi-Tenant by Design – Tenant isolation enforced at the database layer (RLS)
Event-Driven – Real-time ingestion via webhooks and async processing via queues or serverless jobs
Future-Proof – Built for MCP Agents and multimodal interaction
Deployment-Flexible – Optimized for Vercel + Supabase; compatible with self-hosted NestJS + Postgres + Redis

2. Target Use Cases

Primary Use Cases

Use Case	Description
AI Search Sidecar	Sync data from PIMCore/Akeneo → Serve AI-powered semantic search
Central Product Catalog	Unified catalog for B2B/B2C platforms with multi-supplier support
MCP/LLM Backend	Product information backend for AI agents and conversational commerce
Multi-Channel Feeder	Master catalog that validates and syncs to Amazon/Shopify/Google
Distributor Catalog	Manage supplier offers, match products, select best prices
Vercel + Supabase Hosted	Single-tenant or multi-tenant catalog running entirely on Vercel + Supabase

Example Deployment Scenarios

Scenario 1: AI Upgrade for Legacy PIM

PIMCore → Stella Bridge (webhook) → Stella Catalog → AI Search API → Frontend

Scenario 2: Multi-Supplier Distributor

Supplier Feeds → Stella Ingest → SupplierOffers → Matching → CanonicalProducts → Sales Channels

Scenario 3: AI Agent Commerce

Customer Query → AI Agent → MCP Tools → Stella Catalog → Product Recommendations

Scenario 4: Containerised Cloud Deployment

Container/VM (NestJS API + Agent Runtime) + Managed Postgres (e.g. Supabase, RDS) → Stella Catalog

3. Technology Stack

Canonical Stack (Self-Hosted)

Component	Technology
Backend	NestJS (TypeScript strict)
Frontend / Admin	Next.js
ORM	Prisma
Validation	Zod (canonical for DTOs, MCP I/O, tests)
API Style	REST with `/v1/` prefix; MCP tools as thin adapters
Testing	Vitest + fast-check (property-based)
Queue	PostgreSQL outbox + LISTEN/NOTIFY (default); BullMQ adapter optional
Observability	OpenTelemetry; structured JSON logs

Data Layer

Component	Technology
Database	PostgreSQL 15+
Extensions	pgvector, LTREE, uuid-ossp, pgcrypto, pg_trgm
Tenant Isolation	Row-Level Security (RLS) – Mandatory
Queue (default)	PostgreSQL outbox + LISTEN/NOTIFY
Queue (high-throughput)	BullMQ adapter (optional; Redis required)
Object Storage	S3-compatible (MinIO for dev; Supabase Storage when using Supabase)

Search & AI

Component	Technology
Vector Storage	pgvector (colocated with Postgres)
Hybrid Search	Vector similarity + fulltext (GIN)
Embedding Models	Configurable (OpenAI, Cohere, local)

Authentication

Component	Technology
Strategy	Strict delegation (no embedded auth)
Standards	OAuth2 / OpenID Connect
Token Format	JWT with required claims: `sub`, `tenant_id`, `roles`
Vercel + Supabase	Supabase Auth (JWT); map tenant via `app_metadata` or custom claim

Vercel + Supabase Alignment

⚠️ SUPERSEDED — The canonical deployment model is a standalone long-running NestJS process. See architecture_v3.md §15 Deployment Strategy. The table below is retained for historical context only; do not use it for new implementation decisions.

Concern	Self-Hosted (canonical)	Vercel + Supabase (historical)
Database	Any PostgreSQL	Supabase (Postgres) – pgvector & ltree supported
Auth	Any OIDC (e.g. Keycloak)	Supabase Auth – JWT with custom claims
API / Backend	NestJS standalone process	~~Next.js Route Handlers or NestJS on Vercel serverless~~
Media Storage	S3 / MinIO	Supabase Storage (S3-compatible API)
Background Jobs	PostgreSQL outbox + LISTEN/NOTIFY	~~Inngest / Trigger.dev / Vercel Cron~~
Hosting	Any VPS / container / k8s	~~Vercel (frontend + serverless API)~~

Compatibility is maintained by:

Using Prisma with a single schema that works against any Postgres (including Supabase)
Using Zod for all contracts so API shape is independent of runtime
Abstracting the job queue behind an interface (@constellation-platform/jobs): PostgreSQL outbox by default, BullMQ adapter for high-throughput
Using Supabase Auth JWT when deployed on Supabase; same tenant_id + RLS model applies

4. Architecture Overview

High-Level Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                              External Systems                                │
├─────────────────────────────────────────────────────────────────────────────┤
│  Identity / Supabase Auth   Legacy PIM    E-commerce      MCP Agents        │
│  (Keycloak / Supabase)    (PIMCore/Akeneo) (Amazon/Shopify)                 │
└────────┬─────────────────┬──────────────────┬─────────────────┬─────────────┘
         │                 │                  │                 │
         ▼                 ▼                  ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                               API Layer                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  REST API          Ingest Webhook       Channel API        MCP Tools        │
│  /v1/products      /v1/ingest/webhook   /v1/channels       search/compare   │
│  /v1/search        /v1/supplier-offers  /v1/shares         get_context      │
│  (NestJS or Next.js Route Handlers when on Vercel)                           │
└────────┬─────────────────┬──────────────────┬─────────────────┬─────────────┘
         │                 │                  │                 │
         ▼                 ▼                  ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                             Service Layer                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  Auth Guard    Product Service    Search Service    Channel Service         │
│  Tenant Svc    Taxonomy Service   Embedding Svc     CPQ Service             │
│  Ingest Svc    Mapping Service    Media Service     Reference Catalog Svc   │
└────────┬─────────────────┬──────────────────┬─────────────────┬─────────────┘
         │                 │                  │                 │
         ▼                 ▼                  ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              Data Layer                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  PostgreSQL (Supabase or self-hosted) + pgvector + LTREE                    │
│  RLS enforced on all tenant-scoped tables                                    │
│  Redis + BullMQ (self-hosted)  OR  Inngest/Trigger.dev (Vercel)             │
│  S3 / Supabase Storage (media, tenant-namespaced)                            │
└─────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Background Processing                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  Self-hosted: Embedding Worker, Media Worker, Bulk Import, Outbox           │
│  Vercel: Inngest/Trigger.dev jobs or Vercel Cron + serverless functions      │
└─────────────────────────────────────────────────────────────────────────────┘

Repository Shape (Monorepo)

apps/
├── api/                    # NestJS backend (self-hosted) or Next.js API (Vercel)
├── admin/                  # Next.js admin UI (deploys to Vercel)
packages/
├── contracts/              # Zod schemas and shared types
├── config/                 # Lint, tsconfig, tooling presets
└── sdk/                    # Optional: typed API / MCP helpers

5. Vercel + Supabase Deployment

Why Vercel + Supabase

Vercel: Hosts the Next.js application (admin UI and, if desired, API routes or serverless functions). No server management, global CDN, and simple Git-based deployments.
Supabase: Managed PostgreSQL with pgvector and ltree, built-in Auth (JWT), and Storage. Same RLS and tenant model applies.

Deployment Modes

⚠️ SUPERSEDED — See architecture_v3.md §15 Deployment Strategy. The canonical mode is "Self-Hosted / Containerised" below. The Vercel + Supabase row is retained for historical context only.

Mode	Frontend	API	Database	Auth	Storage	Workers
Self-Hosted / Containerised (canonical)	Next.js (any host)	NestJS standalone process	Any PostgreSQL 16+	Any OIDC	S3/MinIO	PostgreSQL outbox (BullMQ optional)
~~Vercel + Supabase~~ (historical)	Vercel (Next.js)	~~Vercel serverless~~	Supabase Postgres	Supabase Auth	Supabase Storage	~~Inngest / Trigger.dev~~

Supabase Compatibility Checklist

PostgreSQL: Use Prisma with connection string from Supabase. Enable extensions in Supabase dashboard or via migration: pgvector, ltree, uuid-ossp, pgcrypto, pg_trgm.
RLS: Create policies as in the design doc; set app.tenant_id from JWT before queries (e.g. from Supabase Auth custom claim or app_metadata).
Auth: Use Supabase Auth; store tenant_id in app_metadata or a custom claim so JWT contains tenant_id for RLS and service logic.
Storage: Use Supabase Storage buckets; key media as {tenant_id}/products/{product_id}/... to preserve tenant isolation.
Edge Functions (optional): Use for lightweight async work (e.g. webhook processing, small embedding batches) if you prefer not to use Inngest/Trigger.dev.

Vercel Compatibility Checklist

Next.js: Build the admin app (and optionally API) as a Next.js app; deploy to Vercel. Use Route Handlers or API routes for REST endpoints if not using a separate NestJS API.
Serverless limits: Avoid long-running processes. Use Inngest, Trigger.dev, or Vercel Cron for background jobs; keep embedding and bulk work in small, idempotent jobs.
Environment: Store Supabase URL, anon key, service role key (for server-side only), and any embedding API keys in Vercel environment variables.

Recommended Stack for “Simple” Vercel + Supabase

⚠️ SUPERSEDED — This section described a Vercel serverless deployment path. The canonical runtime is a standalone long-running NestJS process (see architecture_v3.md §15). The Supabase-managed Postgres and Auth components remain viable as infrastructure providers behind the canonical NestJS runtime.

~~1. Next.js on Vercel (App Router + Route Handlers for /v1/* or a subset).~~ ~~2. Prisma pointing at Supabase Postgres (same schema as self-hosted).~~ ~~3. Supabase Auth for login; JWT includes tenant_id (e.g. via app_metadata).~~ ~~4. Supabase Storage for product media.~~ ~~5. Inngest or Trigger.dev for embedding jobs, bulk import, and other async work (both work with Vercel serverless).~~

Canonical stack: NestJS standalone process → Prisma → Any PostgreSQL 16+ (including Supabase-managed) → Any OIDC provider (including Supabase Auth) → S3-compatible storage → PostgreSQL outbox workers.

6. Multi-Tenancy Model

Strategy

Shared Database, Shared Schema with tenant_id on all core tables
PostgreSQL Row-Level Security (RLS) – Mandatory for all tenant-scoped tables
All queries automatically scoped by tenant_id via RLS policies

Intentional exception to common platform standard. The Common_Technology_Platform_v1.md recommends schema-per-module separation within a single PostgreSQL instance. Stella intentionally uses a single shared schema because:

Cross-module joins — product search spans products, taxonomy, offers, and suppliers in a single query; schema separation would force either cross-schema joins (losing RLS coherence) or data duplication.

RLS coherence — all tenant-scoped policies reference the same app.tenant_id session variable; a unified schema keeps the RLS surface auditable in one place.

Compensating boundaries — module isolation is enforced at the code level (import-table rules, no cross-module ORM relations, CI linter for boundary violations) rather than at the schema level. See architecture_v3.md §4 for repo topology and module isolation rules.

Why RLS?

RLS ensures that even if application code misses a WHERE tenant_id = ? clause, the database prevents data leakage between tenants. This works the same on Supabase or self-hosted Postgres.

Media Isolation

Media assets are namespaced by tenant in object storage (S3 or Supabase Storage):

media/{tenant_id}/products/{product_id}/image_001.jpg

Tenant Configuration

Each tenant can configure:

JSON schemas for product validation
Promoted attributes for faceted search
Re-ranking rules for search results
Embedding model preferences
Rate limit overrides (within platform maximums)

7. Core Domain Model

Product

The central entity representing a catalog item:

Field	Type	Description
`id`	UUID	Stella-generated unique identifier
`tenant_id`	UUID	Owning tenant (RLS enforced)
`external_id`	string	Reference to source system ID
`external_source`	string	Source system identifier (e.g., "pimcore_prod")
`external_updated_at`	timestamp	Source system timestamp for conflict resolution
`title`	string	Product title
`description`	text	Product description
`status`	enum	draft, active, archived
`attributes`	JSONB	Flexible attribute storage
`category_path`	LTREE	Category hierarchy path
`media_references`	JSONB	Links to media assets
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

Product Relationships

Type	Cardinality	Description
Variants	Parent → Children	Size/color variations
Accessories	Many-to-Many	Compatible products
Replacements	One-to-Many	Successor products
Bundles	One-to-Many	Kit components

Category Taxonomy

Categories use PostgreSQL LTREE for efficient hierarchical queries:

Electronics.Audio.Headphones.Wireless

Benefits:

Efficient subtree queries ("find all products under Audio")
Category paths included in embeddings for semantic precision
Move operations propagate to all descendants
Supported on Supabase Postgres (enable ltree extension)

8. AI & Discovery Layer

Embedding Generation

Product text content is hashed (SHA-256)
If hash differs from stored content_hash, generate new embedding
Category paths are flattened and included in embedding text
Embeddings stored in pgvector with model version tracking

Hybrid Search Pipeline

Query → Faceted Filters (GIN) → Vector Search (pgvector) → Re-Ranking → Results

Re-Ranking Rules

Tenants can configure business logic re-ranking:

Boost specific fields (brand, category)
Penalize out-of-stock items
Apply recency boost
Custom scorer DSL

MCP Tools

AI agents interact via Model Context Protocol:

Tool	Description
`search_products`	Semantic search with natural language
`compare_products`	Structured attribute comparison
`get_product_context`	Reference price and availability
`generate_quote`	CPQ pricing for AI agents

9. Integration & Replication

Active Replication (Sidecar Mode)

Stella can sync with legacy PIMs in real-time without requiring migration:

PIMCore → object.postUpdate → Stella Bridge → /v1/ingest/webhook → Stella Catalog

Conflict Resolution

Incoming payloads include external_updated_at timestamp
If payload is older than current data → discard
If payload is newer → upsert and trigger embedding generation (via queue or serverless job)

Schema Mapping

Tenants define JSON schemas for webhook validation
Transformation rules map legacy formats to Stella attributes
Example: PIMCore Object Bricks → Faceted Attributes

Channel Syndication

Define channel schemas (Amazon, Shopify, GS1)
Validate products before syndication
Prevent downstream errors (missing ASIN, invalid GTIN)

10. Multi-Supplier Product Management

Overview

For distributors and retailers sourcing from multiple suppliers, Stella provides a three-tier model:

SupplierOffer (atomic) → OfferGroupMembership → CanonicalProduct (unified)

SupplierOffer

Atomic record from each supplier:

supplier_id, supplier_sku
price, currency, availability
ean, mpn, manufacturer
Product attributes

CanonicalProduct

Unified product grouping multiple supplier offers:

Computed fields: offer_count, lowest_price
Lifecycle: active, merged, split, archived
Enrichment from reference catalogs

OfferGroupMembership

Links offers to canonicals with review workflow:

confidence_score (0.0 - 1.0)
match_type (ean_exact, mpn_exact, name_similarity)
status (suggested, confirmed, rejected, superseded)

Matching Workflow

Auto-match: EAN exact match (0.95 confidence) → auto-confirm eligible
Suggest: MPN + manufacturer match (0.85) → suggest confirm
Review: Name similarity only → manual review required

Offer Selection Policies

When displaying a canonical product, select the "winning" offer:

cheapest – Lowest price
preferred_supplier – Configured supplier priority
highest_availability – Best stock level

11. Reference Catalog Integration

Overview

Stella integrates with industry-standard reference catalogs for product enrichment and matching:

Catalog	Type	License
IceCat	Product Data	Commercial
Etilize	Product Data	Commercial
Amazon	Product Data	API Terms
ETIM	Classification	Open/Commercial
UNSPSC	Classification	Open
eClass	Classification	Commercial

System-Level Catalogs

Reference catalogs are system-level (not tenant-owned):

Shared across all tenants
Read-only for tenants
Updated via sync jobs (scheduled or triggered)

License Enforcement

Commercial catalogs require per-tenant licenses:

License validation before data access
Usage tracking for metered licenses
Expiration and revocation support

Enrichment Workflow

Match SupplierOffer to ReferenceProduct (EAN, MPN, ASIN)
Pull descriptions, images, specifications
Apply to CanonicalProduct
Track enrichment source for attribution

Overview

Catalog owners can share their catalog with controlled permissions:

Share Type	Description
User	Invite specific users via email
Public	Generate shareable link (token-based)
API Key	Programmatic access for integrations

Permissions

Permission	Capability
`view`	Browse products
`search`	Use search functionality
`export`	Download catalog data

Scope Options

All: Entire catalog
Categories: Specific LTREE paths
Filter: Custom product filter

Security Features

Unique cryptographic share tokens
Expiration dates
Instant revocation
Rate limiting
Field exclusion (hide cost, supplier_id)
Access metrics tracking

13. CPQ & Pricing

Pricing Rules

Dynamic pricing with priority-based rule evaluation:

Rule Type	Description
Percentage	Discount/markup by percentage
Fixed	Fixed amount adjustment
Fixed Price	Override to specific price
Tiered	Quantity break pricing

Rule Conditions

Customer segment
Quantity thresholds
Product category
Custom fields

Evaluation Modes

CUMULATIVE: Stack multiple rules
TERMINAL: Stop at first match

Sales Channels

Configure channel-specific pricing and product visibility:

Product filters (categories, suppliers, price range)
Channel-specific pricing rules
Offer selection policies

Competitive Pricing

Integrate competitor price data
Track price position (above/below market)
Historical trend analysis
Alert on significant changes

14. Operational Features

Health Endpoints

Endpoint	Purpose
`GET /v1/health`	Liveness probe (static OK)
`GET /v1/ready`	Readiness probe (checks DB, optional queue/storage)

Observability

Tracing: OpenTelemetry with NewRelic/Datadog/Jaeger support
Metrics: Request latency, queue depth (when applicable), connection pool
Logging: Structured JSON with correlation IDs

Background Processing

Default: PostgreSQL outbox + LISTEN/NOTIFY — exponential backoff retry, dead letter queue, no Redis dependency
High-throughput adapter: BullMQ (Redis) available via @constellation-platform/jobs config flag; swap per-module without architecture change
All jobs must be idempotent regardless of queue backend

CLI Commands

stella-cli init                    # Initialize database and RBAC
stella-cli queue worker embeddings # Start embedding worker (self-hosted)
stella-cli queue status embeddings # Check queue status
stella-cli db migrate              # Apply migrations (Prisma)
stella-cli search reindex           # Rebuild embeddings
stella-cli tenant create            # Create new tenant
stella-cli tenant list              # List all tenants
stella-cli validate-product        # Validate product against channel

Performance Targets

Operation	Target (p95)
Search query	< 500ms
Product creation	< 200ms
Bulk import	1000 products/min

15. Security

Authentication

JWT tokens from external OAuth2/OIDC (e.g. Supabase Auth when on Supabase)
Required claims: sub, tenant_id, roles
Role-based access control on endpoints

Data Protection

RLS enforces tenant isolation at database level (Supabase and self-hosted)
AES-256 encryption for sensitive data at rest
API key rotation with configurable expiration
Parameterized queries (no SQL injection)

Input Validation

Zod schemas for all API inputs
Content-Type header validation
Sanitized error messages

Audit Trail

All mapping decisions logged
Canonical merge/split operations tracked
Authentication failures logged with source IP

16. API Reference

Core Endpoints

Method	Endpoint	Description
POST	`/v1/products`	Create product
GET	`/v1/products`	List products
GET	`/v1/products/:id`	Get product
PUT	`/v1/products/:id`	Update product
DELETE	`/v1/products/:id`	Delete product
POST	`/v1/search`	Hybrid search
GET	`/v1/products/:id/similar`	Similar products

Ingest Endpoints

Method	Endpoint	Description
POST	`/v1/ingest/webhook`	Receive product updates

Multi-Supplier Endpoints

Method	Endpoint	Description
POST	`/v1/supplier-offers`	Create offer
GET	`/v1/supplier-offers`	List offers
POST	`/v1/supplier-offers/bulk`	Bulk upsert
GET	`/v1/supplier-offers/unmatched`	Unmatched offers
POST	`/v1/canonical-products`	Create canonical
GET	`/v1/canonical-products/:id/offers`	Get linked offers
POST	`/v1/canonical-products/merge`	Merge canonicals

Reference Catalog Endpoints

Method	Endpoint	Description
GET	`/v1/reference-catalogs`	List catalogs
GET	`/v1/reference-catalogs/:id/products`	Search reference products
POST	`/v1/admin/licenses`	Grant license
DELETE	`/v1/admin/licenses/:id`	Revoke license

Method	Endpoint	Description
POST	`/v1/shares`	Create share
GET	`/v1/shares`	List shares
DELETE	`/v1/shares/:id`	Revoke share
GET	`/v1/public/catalogs/:shareToken`	Access shared catalog

17. Requirements Summary

Stella Catalog implements 30 requirements covering:

Category	Requirements
Core Product Management	1–4
Integration & Replication	5–7
Security & Auth	8, 23, 30
Media & Background	9, 11
MCP & AI	10
Tenant Management	12
Operations	13, 20, 24, 25
CPQ & Pricing	14–16
Product Matching	17–18
CLI	19
Performance & Retention	21–22
Catalog Sharing	26
Reference Catalogs	27
Versioning & Lifecycle	28–29

See the full requirements document (.kiro/specs/stella-catalog/requirements.md) for detailed acceptance criteria.

18. Correctness Properties

Stella Catalog defines 60 correctness properties validated using property-based testing (fast-check) with minimum 100 iterations per property. Key properties include tenant isolation, LTREE round-trip, embedding dirty checking, webhook conflict resolution, mapping confidence, share token uniqueness, reference catalog isolation, license enforcement, version integrity, lifecycle event delivery, and role permission enforcement. See the full design document for the complete list.

19. Development Environment

Local Development (Self-Hosted)

# docker-compose.dev.yml
version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: stella_catalog
      POSTGRES_USER: stella
      POSTGRES_PASSWORD: development
    ports:
      - '5432:5432'

  redis:
    image: redis:7-alpine
    ports:
      - '6379:6379'

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    ports:
      - '9000:9000'
      - '9001:9001'

  keycloak:
    image: quay.io/keycloak/keycloak:23.0
    command: start-dev --import-realm
    ports:
      - '8080:8080'

Local Development (Vercel + Supabase)

Use Supabase local (optional) or a hosted Supabase project for dev.
Run Next.js locally with npm run dev; point Prisma to your Supabase Postgres URL.
Use Inngest Dev Server or Trigger.dev dev for local job testing.

Development Commands

# Start services (self-hosted)
docker-compose -f docker-compose.dev.yml up -d

# Install dependencies
npm install

# Initialize database
npm run cli init

# Run migrations (Prisma)
npm run cli db migrate   # or: npx prisma migrate dev

# Start development server
npm run start:dev        # NestJS  OR  npm run dev (Next.js)

# Run tests
npm test
npm run test:pbt

20. Versioning & Lifecycle Management

Canonical Product Versioning

Version history for canonical product attributes
Draft editing and publish workflow
Version comparison and rollback

Product Lifecycle Triggers

Webhook events: product.created, product.updated, product.status_changed, canonical.merged, canonical.split, offer.matched, offer.unmatched. Delivery can be implemented via outbox or serverless (e.g. Inngest) when on Vercel.

21. Role & Permission Matrix

Platform roles: super_admin, platform_support. Tenant roles: tenant_admin, catalog_manager, viewer. Permissions align with the matrix in the original requirements spec (manage tenants, reference catalogs, licenses, tenant settings, pricing, products, canonicals, mapping, shares, view, search, export). JWT must include sub, tenant_id, roles, and scope (platform vs tenant).

22. GraphQL Interface (Phase 2 Roadmap)

Planned: optional GraphQL interface alongside REST (product/search queries, mutations, subscriptions). Schema preview and federation are as in the original spec.

23. Embedding Cache Invalidation Strategy

Invalidation triggers: product content change, category rename/move, taxonomy restructure, embedding model upgrade. Flow: identify affected products → queue jobs (BullMQ or Inngest/Trigger.dev) → regenerate and store embeddings. Configuration (batch size, delay, priority) as in the original spec.

24. Reference Catalog Prioritization

Enrichment precedence: tenant-configured primary → commercial (IceCat, Etilize) → Amazon → classification (ETIM, UNSPSC). Conflict resolution by field type (descriptions, images, specifications, classifications) as in the original spec.

25. Enhanced Security Features

Sensitive data masking, public share link security (time-bound tokens, optional IP allowlist, access logging, rate limiting, revocation) as in the original spec.

26. Updated Performance Targets

Operation	Initial Target (p95)	Stretch Target (p95)
Search query	< 800ms	< 500ms
Product creation	< 200ms	< 100ms
Bulk import	1000 products/min	2000 products/min
Embedding generation	< 2s per product	< 1s per product

27. Extended CLI Commands

Same as original: tenant create/list/suspend, reference-catalog import, validate-product, bulk-import, bulk-match, diagnose. CLI name: stella-cli (or npm run cli).

Appendix: Document History

Version	Date	Changes
v6 (Stella)	Jan 2026	Multi-supplier, Reference catalogs, Catalog sharing, CPQ, correctness properties, CLI, Observability
v1 (Stella)	Mar 2026	Renamed to Stella Catalog; standalone stack (NestJS, Next.js, Prisma, Zod, BullMQ); Vercel + Supabase deployment path; compatibility preserved for simple hosting

Feedback

This specification is open for review. Please provide feedback on:

Requirements completeness – Are there missing use cases?
Vercel + Supabase fit – Does the compatibility model cover your deployment needs?
Technical feasibility – Are the proposed solutions practical?
API design – Are the endpoints intuitive and RESTful?
Security model – Are there gaps in the security approach?

Submit feedback via GitHub issues or pull requests.

Technical Product Specification v1​

Executive Summary​

Purpose​

Key Benefits​

Who Should Use Stella Catalog?​

Open Source License​

Table of Contents​

1. Vision & Core Principles​

Vision​

Core Design Principles​

2. Target Use Cases​

Primary Use Cases​

Example Deployment Scenarios​

3. Technology Stack​

Canonical Stack (Self-Hosted)​

Data Layer​

Search & AI​

Authentication​

Vercel + Supabase Alignment​

4. Architecture Overview​

High-Level Diagram​

Repository Shape (Monorepo)​

5. Vercel + Supabase Deployment​

Why Vercel + Supabase​

Deployment Modes​

Supabase Compatibility Checklist​

Vercel Compatibility Checklist​

Recommended Stack for “Simple” Vercel + Supabase​

6. Multi-Tenancy Model​

Strategy​

Why RLS?​

Media Isolation​

Tenant Configuration​

7. Core Domain Model​

Product​

Product Relationships​

Category Taxonomy​

8. AI & Discovery Layer​

Embedding Generation​

Hybrid Search Pipeline​

Re-Ranking Rules​

MCP Tools​

9. Integration & Replication​

Active Replication (Sidecar Mode)​

Conflict Resolution​

Schema Mapping​

Channel Syndication​

10. Multi-Supplier Product Management​

Overview​

SupplierOffer​

CanonicalProduct​

OfferGroupMembership​

Matching Workflow​

Offer Selection Policies​

11. Reference Catalog Integration​

Overview​

System-Level Catalogs​

License Enforcement​

Enrichment Workflow​

12. Catalog Sharing​

Overview​

Permissions​

Scope Options​

Security Features​

13. CPQ & Pricing​

Pricing Rules​

Rule Conditions​

Evaluation Modes​

Sales Channels​

Competitive Pricing​

14. Operational Features​

Health Endpoints​

Observability​

Background Processing​

CLI Commands​

Performance Targets​

15. Security​

Authentication​

Data Protection​

Input Validation​

Technical Product Specification v1

Executive Summary

Purpose

Key Benefits

Who Should Use Stella Catalog?

Open Source License

Table of Contents

1. Vision & Core Principles

Vision

Core Design Principles

2. Target Use Cases

Primary Use Cases

Example Deployment Scenarios

3. Technology Stack

Canonical Stack (Self-Hosted)

Data Layer

Search & AI

Authentication

Vercel + Supabase Alignment

4. Architecture Overview

High-Level Diagram

Repository Shape (Monorepo)

5. Vercel + Supabase Deployment

Why Vercel + Supabase

Deployment Modes

Supabase Compatibility Checklist

Vercel Compatibility Checklist

Recommended Stack for “Simple” Vercel + Supabase

6. Multi-Tenancy Model

Strategy

Why RLS?

Media Isolation

Tenant Configuration

7. Core Domain Model

Product

Product Relationships

Category Taxonomy

8. AI & Discovery Layer

Embedding Generation

Hybrid Search Pipeline

Re-Ranking Rules

MCP Tools

9. Integration & Replication

Active Replication (Sidecar Mode)

Conflict Resolution

Schema Mapping

Channel Syndication

10. Multi-Supplier Product Management

Overview

SupplierOffer

CanonicalProduct

OfferGroupMembership

Matching Workflow

Offer Selection Policies

11. Reference Catalog Integration

Overview

System-Level Catalogs

License Enforcement

Enrichment Workflow

12. Catalog Sharing

Overview

Permissions

Scope Options

Security Features

13. CPQ & Pricing

Pricing Rules

Rule Conditions

Evaluation Modes

Sales Channels

Competitive Pricing

14. Operational Features

Health Endpoints

Observability

Background Processing

CLI Commands

Performance Targets

15. Security

Authentication

Data Protection

Input Validation