autostore/nestjs/PLAN.md

NestJS Implementation Plan for AutoStore

Overview

Implementation of AutoStore system using NestJS with TypeScript, following Clean Architecture principles. The system stores items with expiration dates and automatically orders new items when they expire.

Architecture Approach

• Clean Architecture with clear separation of concerns
• Domain-Driven Design with rich domain models
• Hexagonal Architecture with dependency inversion
• Repository Pattern for data persistence
• CQRS-like command/query separation
• Dependency Injection leveraging NestJS IoC container

Core Domain Logic

ItemExpirationSpec - Single Source of Truth for Expiration

File: src/domain/specifications/item-expiration.spec.ts Purpose: Centralized expiration checking logic - the single source of truth for determining if items are expired

Key Methods:

• isExpired(item: ItemEntity, currentTime: Date): boolean - Checks if item expired
• getSpec(currentTime: Date): Specification<ItemEntity> - Returns specification for repository queries

Place in the flow:

• Called by AddItemCommand.execute() to check newly created items for immediate expiration
• Called by HandleExpiredItemsCommand.execute() to find expired items for processing
• Used by ItemRepository.findWhere() to query database for expired items

Detailed Implementation Plan

Domain Layer

1. Entities

File: src/domain/entities/item.entity.ts Purpose: Core business entity representing an item

Key Methods:

• constructor(id: ItemId, name: string, expirationDate: ExpirationDate, orderUrl: string, userId: UserId): void - Creates item with validation
• Getters for all properties

Place in the flow:

• Created by AddItemCommand.execute()
• Retrieved by ItemRepository methods
• Passed to ItemExpirationSpec.isExpired() for expiration checking

File: src/domain/entities/user.entity.ts Purpose: User entity for item ownership and authentication purposes

Key Methods:

• constructor(id: UserId, username: string, passwordHash: string): void - Creates user with validation
• Getters for all properties

2. Value Objects

File: src/domain/value-objects/item-id.vo.ts Purpose: Strong typing for item identifiers

Key Methods:

• constructor(value: string): void - Validates UUID format
• getValue(): string - Returns string value
• equals(other: ItemId): boolean - Compares with another ItemId

File: src/domain/value-objects/expiration-date.vo.ts Purpose: Immutable expiration date with validation

Key Methods:

• constructor(value: Date): void - Validates date format (allows past dates per business rules)
• getValue(): Date - Returns Date object
• format(): string - Returns ISO string format

Place in the flow:

• Used by ItemEntity constructor for type-safe date handling
• Validated by ItemExpirationSpec.isExpired() for expiration logic

3. Specifications

File: src/domain/specifications/specification.interface.ts Purpose: Generic specification pattern interface

Key Methods:

• isSatisfiedBy(candidate: T): boolean - Evaluates specification
• getSpec(): object - Returns specification object for repository implementation

Place in the flow:

• Implemented by ItemExpirationSpec for type-safe specifications
• Used by ItemRepository.findWhere() for database queries

Application Layer

4. Commands

File: src/application/commands/add-item.command.ts Purpose: Use case for creating new items with expiration handling

Key Methods:

• constructor(itemRepo: IItemRepository, orderService: IOrderService, timeProvider: ITimeProvider, expirationSpec: ItemExpirationSpec, logger: Logger): void - Dependency injection
• execute(name: string, expirationDate: string, orderUrl: string, userId: string): Promise<string | null> - Creates item, handles expired items immediately

Flow:

1. ItemsController.createItem() calls AddItemCommand.execute()
2. Creates ItemEntity with validated data
3. Calls ItemExpirationSpec.isExpired() to check if item is expired
4. If expired:
   • calls OrderHttpService.orderItem()
   • returns item ID (business rule: expired items trigger ordering but still return ID field that might be empty or invalid)
5. If not expired: calls ItemRepository.save() and returns item ID

File: src/application/commands/handle-expired-items.command.ts Purpose: Background command to process expired items

Key Methods:

• constructor(itemRepo: IItemRepository, orderService: IOrderService, timeProvider: ITimeProvider, expirationSpec: ItemExpirationSpec, logger: Logger): void - Dependency injection
• execute(): Promise<void> - Finds and processes all expired items

Flow:

1. ExpiredItemsScheduler.handleCron() calls HandleExpiredItemsCommand.execute()
2. Gets current time from ITimeProvider
3. Calls ItemExpirationSpec.getSpec() to get expiration specification
4. Calls ItemRepository.findWhere() to find expired items
5. For each expired item: calls OrderHttpService.orderItem() then ItemRepository.delete()

File: src/application/commands/delete-item.command.ts Purpose: Use case for deleting user items

Key Methods:

• constructor(itemRepo: IItemRepository, logger: Logger): void - Dependency injection
• execute(itemId: string, userId: string): Promise<void> - Validates ownership and deletes item

Flow:

1. ItemsController.deleteItem() calls DeleteItemCommand.execute()
2. Calls ItemRepository.findById() to retrieve item
3. Validates ownership by comparing user IDs
4. Calls ItemRepository.delete() to remove item

File: src/application/commands/login-user.command.ts Purpose: User authentication use case

Key Methods:

• constructor(authService: IAuthService, logger: Logger): void - Dependency injection
• execute(username: string, password: string): Promise<string> - Authenticates and returns JWT token

5. Queries

File: src/application/queries/get-item.query.ts Purpose: Retrieves single item by ID with authorization

Key Methods:

• constructor(itemRepo: IItemRepository, logger: Logger): void - Dependency injection
• execute(itemId: string, userId: string): Promise<ItemEntity> - Validates ownership and returns item

Flow:

1. ItemsController.getItem() calls GetItemQuery.execute()
2. Calls ItemRepository.findById() to retrieve item
3. Validates ownership by comparing user IDs
4. Returns item entity

File: src/application/queries/list-items.query.ts Purpose: Retrieves all items for authenticated user

Key Methods:

• constructor(itemRepo: IItemRepository, logger: Logger): void - Dependency injection
• execute(userId: string): Promise<ItemEntity[]> - Returns user's items

Flow:

1. ItemsController.listItems() calls ListItemsQuery.execute()
2. Calls ItemRepository.findByUserId() to retrieve user's items
3. Returns array of item entities

6. DTOs

File: src/application/dto/create-item.dto.ts Purpose: Request validation for item creation

Key Properties:

• name: string - Item name (min: 1, max: 255)
• expirationDate: string - ISO date string (future date validation)
• orderUrl: string - Valid URL format

Place in the flow:

• Used by ItemsController.createItem() for request body validation

File: src/application/dto/item-response.dto.ts Purpose: Standardized item response format

Key Properties:

• id: string - Item ID
• name: string - Item name
• expirationDate: string - ISO date string
• orderUrl: string - Order URL
• userId: string - Owner user ID
• createdAt: string - Creation timestamp

Place in the flow:

• Used by all item controller methods for response transformation

Infrastructure Layer

7. Repositories

File: src/infrastructure/repositories/file-item-repository.ts Purpose: File-based implementation of item repository using JSON files

Key Methods:

• save(item: ItemEntity): Promise<void> - Persists item entity
• findById(id: ItemId): Promise<ItemEntity | null> - Finds by ID
• findByUserId(userId: UserId): Promise<ItemEntity[]> - Finds by user
• findWhere(spec: Specification<ItemEntity>): Promise<ItemEntity[]> - Finds by specification using ItemExpirationSpec
• delete(id: ItemId): Promise<void> - Deletes item
• exists(id: ItemId): Promise<boolean> - Checks existence

Place in the flow:

• Called by all commands and queries for data persistence and retrieval
• Uses ItemExpirationSpec for finding expired items

8. HTTP Services

File: src/infrastructure/http/order-http.service.ts Purpose: HTTP implementation of order service

Key Methods:

• constructor(httpService: HttpService, logger: Logger): void - Dependency injection
• orderItem(item: ItemEntity): Promise<void> - Sends POST request to order URL

Place in the flow:

• Called by AddItemCommand.execute() for expired items
• Called by HandleExpiredItemsCommand.execute() for batch processing

9. Authentication

File: src/infrastructure/auth/jwt-auth.service.ts Purpose: JWT implementation of authentication service

Key Methods:

• constructor(userRepo: IUserRepository, jwtService: JwtService, configService: ConfigService, logger: Logger): void - Dependency injection
• authenticate(username: string, password: string): Promise<string | null> - Validates credentials and generates JWT
• validateToken(token: string): Promise<boolean> - Validates JWT token
• getUserIdFromToken(token: string): Promise<string | null> - Extracts user ID from token

Place in the flow:

• Called by LoginUserCommand.execute() for user authentication
• Used by JwtAuthGuard for route protection

Presentation Layer

10. Controllers

File: src/presentation/controllers/items.controller.ts Purpose: REST API endpoints for item management

Key Methods:

• constructor(addItemCmd: AddItemCommand, getItemQry: GetItemQuery, listItemsQry: ListItemsQuery, deleteItemCmd: DeleteItemCommand): void - Dependency injection
• createItem(@Body() dto: CreateItemDto, @Req() req: Request): Promise<ItemResponseDto> - POST /items
• getItem(@Param('id') id: string, @Req() req: Request): Promise<ItemResponseDto> - GET /items/:id
• listItems(@Req() req: Request): Promise<ItemResponseDto[]> - GET /items
• deleteItem(@Param('id') id: string, @Req() req: Request): Promise<void> - DELETE /items/:id

Flow:

• Receives HTTP requests and validates input
• Calls appropriate commands/queries based on HTTP method
• Returns standardized responses with DTOs

File: src/presentation/controllers/auth.controller.ts Purpose: Authentication endpoints

Key Methods:

• constructor(loginUserCmd: LoginUserCommand): void - Dependency injection
• login(@Body() dto: LoginDto): Promise<{ token: string }> - POST /login

11. Guards

File: src/presentation/guards/jwt-auth.guard.ts Purpose: JWT authentication route protection

Key Methods:

• constructor(jwtAuthService: IJwtAuthService, logger: Logger): void - Dependency injection
• canActivate(context: ExecutionContext): Promise<boolean> - Validates JWT and attaches user to request

Place in the flow:

• Applied to all protected routes by NestJS Guard System
• Uses JwtAuthService for token validation

Background Processing

File: src/infrastructure/services/expired-items-scheduler.service.ts Purpose: Scheduled job for processing expired items using NestJS scheduler

Key Methods:

• constructor(handleExpiredItemsCmd: HandleExpiredItemsCommand): void - Dependency injection
• onModuleInit(): Promise<void> - Processes expired items on application startup
• handleExpiredItemsCron(): Promise<void> - Runs every minute (@Cron(CronExpression.EVERY_MINUTE))
• handleExpiredItemsDaily(): Promise<void> - Runs every day at midnight (@Cron('0 0 * * *'))

Flow:

1. On startup: onModuleInit() immediately calls HandleExpiredItemsCommand.execute()
2. Every minute: handleExpiredItemsCron() processes expired items
3. Every midnight: handleExpiredItemsDaily() processes expired items
4. All methods use try-catch to continue operation despite errors
5. Comprehensive logging for monitoring and debugging

Configuration:

• Requires ScheduleModule.forRoot() in AppModule imports
• Uses @nestjs/schedule package for cron expressions
• Implements OnModuleInit for startup processing

Complete Flow Summary

Item Creation Flow

POST /items
├── JwtAuthGuard (authentication)
├── CreateItemDto validation
├── ItemsController.createItem()
│   ├── AddItemCommand.execute()
│   │   ├── ItemEntity constructor (validation)
│   │   ├── ItemExpirationSpec.isExpired() ← SINGLE SOURCE OF TRUTH
│   │   ├── If expired: OrderHttpService.orderItem()
│   │   └── If not expired: ItemRepository.save()
│   └── ItemResponseDto transformation
└── HTTP response

Expired Items Processing Flow

Cron Job (every minute)
└── ExpiredItemsScheduler.handleCron()
    └── HandleExpiredItemsCommand.execute()
        ├── ITimeProvider.now()
        ├── ItemExpirationSpec.getSpec() ← SINGLE SOURCE OF TRUTH
        ├── ItemRepository.findWhere() (using spec)
        ├── For each expired item:
        │   ├── OrderHttpService.orderItem()
        │   └── ItemRepository.delete()
        └── Logging

Item Retrieval Flow

GET /items/:id
├── JwtAuthGuard (authentication)
├── ItemsController.getItem()
│   ├── GetItemQuery.execute()
│   │   ├── ItemRepository.findById()
│   │   ├── Ownership validation
│   │   └── Return ItemEntity
│   └── ItemResponseDto transformation
└── HTTP response

Key Design Principles

1. Single Source of Truth: ItemExpirationSpec is the only component that determines expiration logic
2. Clear Flow: Each component has a well-defined place in the execution chain
3. Dependency Inversion: High-level modules don't depend on low-level modules
4. Separation of Concerns: Each layer has distinct responsibilities
5. Testability: All components can be tested in isolation

This implementation plan ensures consistent development regardless of the implementer, providing clear flow definitions and emphasizing ItemExpirationSpec as the centralized source for expiration logic.