Feature: Savings Product Capacity Management

backend/src/migrations/1791000000000-AddMaxCapacityToSavingsProducts.ts

@@ -0,0 +1,20 @@
+import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';
+
+export class AddMaxCapacityToSavingsProducts1791000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.addColumn(
+      'savings_products',
+      new TableColumn({
+        name: 'maxCapacity',
+        type: 'decimal',
+        precision: 14,
+        scale: 2,
+        isNullable: true,
+      }),
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.dropColumn('savings_products', 'maxCapacity');
+  }
+}

backend/src/modules/admin/admin-savings.controller.ts

@@ -1,4 +1,8 @@
 import {
+  Controller,
+  Get,
+  Post,
+  Patch,
   Body,
   Controller,
   Delete,
@@ -22,6 +26,7 @@ import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard';
 import { RolesGuard } from '../../common/guards/roles.guard';
 import { Roles } from '../../common/decorators/roles.decorator';
 import { Role } from '../../common/enums/role.enum';
+import { ProductCapacitySnapshot } from '../savings/savings.service';
 import { PageOptionsDto } from '../../common/dto/page-options.dto';
 import { CreateProductDto } from '../savings/dto/create-product.dto';
 import { UpdateProductDto } from '../savings/dto/update-product.dto';
@@ -76,4 +81,16 @@ export class AdminSavingsController {
   ) {
     return this.adminSavingsService.getSubscribers(id, opts);
   }
+
+  @Get('products/:id/capacity-metrics')
+  @ApiOperation({ summary: 'Get live capacity utilization metrics (admin)' })
+  @ApiResponse({
+    status: 200,
+    description: 'Live capacity metrics',
+  })
+  async getCapacityMetrics(
+    @Param('id') id: string,
+  ): Promise<ProductCapacitySnapshot> {
+    return await this.savingsService.getProductCapacitySnapshot(id);
+  }
 }

backend/src/modules/notifications/entities/notification.entity.ts

@@ -21,6 +21,7 @@ export enum NotificationType {
   CHALLENGE_BADGE_EARNED = 'CHALLENGE_BADGE_EARNED',
   PRODUCT_ALERT_TRIGGERED = 'PRODUCT_ALERT_TRIGGERED',
   REBALANCING_RECOMMENDED = 'REBALANCING_RECOMMENDED',
+  ADMIN_CAPACITY_ALERT = 'ADMIN_CAPACITY_ALERT',
 }
 
 @Entity('notifications')

backend/src/modules/notifications/notifications.service.ts

@@ -8,6 +8,7 @@ import { MailService } from '../mail/mail.service';
 import { User } from '../user/entities/user.entity';
 import { WaitlistEntry } from '../savings/entities/waitlist-entry.entity';
 import { WaitlistEvent } from '../savings/entities/waitlist-event.entity';
+import { Role } from '../../common/enums/role.enum';
 
 export interface SweepCompletedEvent {
   userId: string;
@@ -426,6 +427,48 @@ export class NotificationsService {
     }
   }
 
+  @OnEvent('savings.capacity.threshold')
+  async handleCapacityAlert(event: {
+    productId: string;
+    utilizationPercentage: number;
+    isFull: boolean;
+  }) {
+    try {
+      const admins = await this.userRepository.find({
+        where: { role: Role.ADMIN },
+        select: ['id'],
+      });
+
+      if (!admins.length) {
+        return;
+      }
+
+      const title = event.isFull
+        ? 'Savings product auto-deactivated'
+        : 'Savings product nearing capacity';
+      const message = event.isFull
+        ? `Product ${event.productId} reached maximum capacity and was auto-deactivated.`
+        : `Product ${event.productId} is ${event.utilizationPercentage}% utilized.`;
+
+      await Promise.all(
+        admins.map((admin) =>
+          this.createNotification({
+            userId: admin.id,
+            type: NotificationType.ADMIN_CAPACITY_ALERT,
+            title,
+            message,
+            metadata: event,
+          }),
+        ),
+      );
+    } catch (error) {
+      this.logger.error(
+        `Error processing savings.capacity.threshold for product ${event.productId}`,
+        error,
+      );
+    }
+  }
+
   /**
    * Create a notification in the database
    */

backend/src/modules/savings/dto/create-product.dto.ts

@@ -77,6 +77,15 @@ export class CreateProductDto {
   @Min(0)
   tvlAmount?: number;
 
+  @ApiPropertyOptional({
+    example: 250000,
+    description: 'Maximum liquidity-backed capacity for the product',
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  maxCapacity?: number;
+
   @ApiPropertyOptional({
     enum: RiskLevel,
     default: RiskLevel.LOW,

backend/src/modules/savings/dto/product-details.dto.ts

@@ -46,6 +46,23 @@ export class ProductDetailsDto {
   @ApiProperty({ description: 'Live total assets formatted as XLM' })
   totalAssetsXlm: number;
 
+  @ApiPropertyOptional({
+    description: 'Maximum liquidity-backed capacity for the product',
+  })
+  maxCapacity: number | null;
+
+  @ApiProperty({ description: 'Current utilized capacity amount' })
+  utilizedCapacity: number;
+
+  @ApiProperty({ description: 'Remaining capacity amount' })
+  availableCapacity: number;
+
+  @ApiProperty({ description: 'Capacity utilization percentage' })
+  utilizationPercentage: number;
+
+  @ApiProperty({ description: 'Whether the product is fully utilized' })
+  isFull: boolean;
+
   @ApiProperty({ description: 'Product creation timestamp' })
   createdAt: Date;
 

backend/src/modules/savings/dto/savings-product.dto.ts

@@ -44,6 +44,20 @@ export class SavingsProductDto {
   @ApiProperty({ description: 'Total Value Locked (aggregated local balance)' })
   tvlAmount: number;
 
+  @ApiPropertyOptional({
+    description: 'Maximum liquidity-backed capacity for the product',
+  })
+  maxCapacity: number | null;
+
+  @ApiProperty({ description: 'Current utilized capacity amount' })
+  utilizedCapacity: number;
+
+  @ApiProperty({ description: 'Remaining capacity amount' })
+  availableCapacity: number;
+
+  @ApiProperty({ description: 'Capacity utilization percentage' })
+  utilizationPercentage: number;
+
   @ApiProperty({ description: 'Product creation timestamp' })
   createdAt: Date;
 

backend/src/modules/savings/entities/savings-product.entity.ts

@@ -54,6 +54,9 @@ export class SavingsProduct {
   @Column('int', { nullable: true })
   capacity: number | null;
 
+  @Column('decimal', { precision: 14, scale: 2, nullable: true })
+  maxCapacity: number | null;
+
   @Column({ default: true })
   isActive: boolean;
 

backend/src/modules/savings/savings.controller.ts

@@ -93,7 +93,7 @@ export class SavingsController {
     description: 'Soroban RPC request timeout',
   })
   async getProductDetails(@Param('id') id: string): Promise<ProductDetailsDto> {
-    const { product, totalAssets } =
+    const { product, totalAssets, capacity } =
       await this.savingsService.findProductWithLiveData(id);
 
     const totalAssetsXlm = totalAssets / 10_000_000;
@@ -111,6 +111,11 @@ export class SavingsController {
       contractId: product.contractId,
       totalAssets,
       totalAssetsXlm,
+      maxCapacity: capacity.maxCapacity,
+      utilizedCapacity: capacity.utilizedCapacity,
+      availableCapacity: capacity.availableCapacity,
+      utilizationPercentage: capacity.utilizationPercentage,
+      isFull: capacity.isFull,
       riskLevel: product.riskLevel || RiskLevel.LOW,
       createdAt: product.createdAt,
       updatedAt: product.updatedAt,