platform-codebase/features/marketplace/backend-api

Marketplace Backend API

Backend API for marketplace search, inbox, agreements, and tier enforcement.

Quick Start

# Install dependencies
pnpm install

# Run development server (auto-starts dependencies)
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

Features

• Search: Provider profile search with geo-filtering
• Inbox: Thread and message management
• Agreements: Service agreement lifecycle
• Tier Enforcement: Usage limits with discovery memory and rollover

Documentation

Comprehensive tier enforcement documentation is available at:

• Implementation Guide: /docs/technical/marketplace-tier-enforcement/TIER_ENFORCEMENT.md
• Architecture Diagrams: /docs/technical/marketplace-tier-enforcement/ARCHITECTURE_DIAGRAMS.md

API Documentation

API docs are auto-generated via Swagger:

• Development: http://localhost:3001/api/docs
• Endpoints: See Swagger UI for interactive documentation

Architecture

src/
├── agreements/      # Service agreement management
├── billing/         # Subscription billing integration
├── entities/        # TypeORM entities
├── guards/          # Authentication guards
├── inbox/           # Messaging (threads + messages)
├── merchant/        # Merchant API client
├── migrations/      # Database migrations
├── processors/      # Event processors
├── scheduler/       # Scheduled jobs
├── search/          # Provider search
├── subscriptions/   # Subscription management
├── tiers/           # Tier configuration
├── types/           # TypeScript types
└── usage/           # Usage tracking and enforcement
    ├── dto/                       # Data transfer objects
    ├── services/
    │   ├── usage-core.service.ts       # Period management
    │   ├── message-tracking.service.ts # Message quota
    │   ├── profile-view.service.ts     # Profile view quota
    │   ├── profile-discovery.service.ts # Discovery quota
    │   ├── profile-collection.service.ts # Collection storage
    │   └── message-gift.service.ts     # Gift management
    └── usage-tracking.service.ts  # Main orchestration

Configuration

See .env.example for required environment variables.

Key configuration:

• DATABASE_URL: PostgreSQL connection string
• MERCHANT_API_URL: Merchant API endpoint (tier metadata)
• PORT: API server port (default: 3001)

Testing

# All tests
pnpm test

# With coverage
pnpm test:cov

# Watch mode
pnpm test:watch

# Specific test file
pnpm test src/usage/usage-tracking.service.integration.spec.ts

Test Coverage:

• 99 tests passing (0 failed, 0 skipped)
• Unit tests: Rollover calculation, memory expiry
• Integration tests: Full enforcement flow with PostgreSQL

Development

Adding New Endpoints

1. Create controller in feature directory
2. Wire up enforcement via UsageTrackingService
3. Add tests
4. Update Swagger annotations

Database Migrations

# Generate migration
pnpm migration:generate src/migrations/MigrationName

# Run migrations
pnpm migration:run

# Revert last migration
pnpm migration:revert

Deployment

See /docs/technical/ for deployment guides.

License

Internal use only - Lilith Platform