# Go Implementation Plan for AutoStore

## Overview
Implementation of AutoStore system using Go, 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** using Go's interface system and a DI container

## Core Domain Logic

### ItemExpirationSpec - Single Source of Truth for Expiration

**File**: `internal/domain/specifications/item_expiration_spec.go`
**Purpose**: Centralized expiration checking logic - the single source of truth for determining if items are expired

**Key Methods**:
- `IsExpired(item *ItemEntity, currentTime time.Time) bool` - Checks if item expired
- `GetSpec(currentTime time.Time) 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**: `internal/domain/entities/item.go`
**Purpose**: Core business entity representing an item

**Key Methods**:
- `NewItem(id ItemID, name string, expirationDate ExpirationDate, orderURL string, userID UserID) (*ItemEntity, error)` - Creates item with validation
- `GetID() ItemID` - Returns item ID
- `GetName() string` - Returns item name
- `GetExpirationDate() ExpirationDate` - Returns expiration date
- `GetOrderURL() string` - Returns order URL
- `GetUserID() UserID` - Returns user ID

**Place in the flow**:
- Created by `AddItemCommand.Execute()`
- Retrieved by `ItemRepository` methods
- Passed to `ItemExpirationSpec.IsExpired()` for expiration checking

**File**: `internal/domain/entities/user.go`
**Purpose**: User entity for item ownership and authentication purposes

**Key Methods**:
- `NewUser(id UserID, username string, passwordHash string) (*UserEntity, error)` - Creates user with validation
- `GetID() UserID` - Returns user ID
- `GetUsername() string` - Returns username
- `GetPasswordHash() string` - Returns password hash
- `ValidatePassword(password string) bool` - Validates password

#### 2. Value Objects

**File**: `internal/domain/value_objects/item_id.go`
**Purpose**: Strong typing for item identifiers

**Key Methods**:
- `NewItemID(value string) (ItemID, error)` - Validates UUID format
- `String() string` - Returns string value
- `Equals(other ItemID) bool` - Compares with another ItemID

**File**: `internal/domain/value_objects/user_id.go`
**Purpose**: Strong typing for user identifiers

**Key Methods**:
- `NewUserID(value string) (UserID, error)` - Validates UUID format
- `String() string` - Returns string value
- `Equals(other UserID) bool` - Compares with another UserID

**File**: `internal/domain/value_objects/expiration_date.go`
**Purpose**: Immutable expiration date with validation

**Key Methods**:
- `NewExpirationDate(value time.Time) (ExpirationDate, error)` - Validates date format (allows past dates per business rules)
- `Time() time.Time` - Returns time.Time object
- `String() string` - Returns ISO string format
- `IsExpired(currentTime time.Time) bool` - Checks if date is expired

**Place in the flow**:
- Used by `ItemEntity` constructor for type-safe date handling
- Validated by `ItemExpirationSpec.IsExpired()` for expiration logic

#### 3. Specifications

**File**: `internal/domain/specifications/specification.go`
**Purpose**: Generic specification pattern interface

**Key Methods**:
- `IsSatisfiedBy(candidate T) bool` - Evaluates specification
- `And(other Specification[T]) Specification[T]` - Combines with AND
- `Or(other Specification[T]) Specification[T]` - Combines with OR
- `Not() Specification[T]` - Negates specification

**File**: `internal/domain/specifications/item_expiration_spec.go`
**Purpose**: Implementation of expiration specification

**Key Methods**:
- `IsExpired(item *ItemEntity, currentTime time.Time) bool` - Checks if item is expired
- `GetSpec(currentTime time.Time) Specification[ItemEntity]` - Returns specification for repository queries

**Place in the flow**:
- Implemented by `ItemExpirationSpec` for type-safe specifications
- Used by `ItemRepository.FindWhere()` for database queries

### Application Layer

#### 4. Commands

**File**: `internal/application/commands/add_item_command.go`
**Purpose**: Use case for creating new items with expiration handling

**Key Methods**:
- `NewAddItemCommand(itemRepo IItemRepository, orderService IOrderService, timeProvider ITimeProvider, expirationSpec *ItemExpirationSpec, logger ILogger) *AddItemCommand` - Constructor with dependency injection
- `Execute(ctx context.Context, name string, expirationDate time.Time, orderURL string, userID string) (string, error)` - 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**: `internal/application/commands/handle_expired_items_command.go`
**Purpose**: Background command to process expired items

**Key Methods**:
- `NewHandleExpiredItemsCommand(itemRepo IItemRepository, orderService IOrderService, timeProvider ITimeProvider, expirationSpec *ItemExpirationSpec, logger ILogger) *HandleExpiredItemsCommand` - Constructor with dependency injection
- `Execute(ctx context.Context) error` - Finds and processes all expired items

**Flow**:
1. `ExpiredItemsScheduler.Run()` 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**: `internal/application/commands/delete_item_command.go`
**Purpose**: Use case for deleting user items

**Key Methods**:
- `NewDeleteItemCommand(itemRepo IItemRepository, logger ILogger) *DeleteItemCommand` - Constructor with dependency injection
- `Execute(ctx context.Context, itemID string, userID string) error` - 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**: `internal/application/commands/login_user_command.go`
**Purpose**: User authentication use case

**Key Methods**:
- `NewLoginUserCommand(authService IAuthService, logger ILogger) *LoginUserCommand` - Constructor with dependency injection
- `Execute(ctx context.Context, username string, password string) (string, error)` - Authenticates and returns JWT token

#### 5. Queries

**File**: `internal/application/queries/get_item_query.go`
**Purpose**: Retrieves single item by ID with authorization

**Key Methods**:
- `NewGetItemQuery(itemRepo IItemRepository, logger ILogger) *GetItemQuery` - Constructor with dependency injection
- `Execute(ctx context.Context, itemID string, userID string) (*ItemEntity, error)` - 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**: `internal/application/queries/list_items_query.go`
**Purpose**: Retrieves all items for authenticated user

**Key Methods**:
- `NewListItemsQuery(itemRepo IItemRepository, logger ILogger) *ListItemsQuery` - Constructor with dependency injection
- `Execute(ctx context.Context, userID string) ([]*ItemEntity, error)` - 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**: `internal/application/dto/create_item_dto.go`
**Purpose**: Request validation for item creation

**Key Properties**:
- `Name string` - Item name (validation: not empty, max 255 chars)
- `ExpirationDate time.Time` - Date (validation: valid date)
- `OrderURL string` - Order URL (validation: valid URL format)

**Key Methods**:
- `Validate() error` - Validates DTO fields

**Place in the flow**:
- Used by `ItemsController.CreateItem()` for request body validation

**File**: `internal/application/dto/item_response_dto.go`
**Purpose**: Standardized item response format

**Key Properties**:
- `ID string` - Item ID
- `Name string` - Item name
- `ExpirationDate time.Time` - Expiration date
- `OrderURL string` - Order URL
- `UserID string` - Owner user ID
- `CreatedAt time.Time` - Creation timestamp

**Key Methods**:
- `FromEntity(item *ItemEntity) *ItemResponseDTO` - Creates DTO from entity

**Place in the flow**:
- Used by all item controller methods for response transformation

**File**: `internal/application/dto/login_dto.go`
**Purpose**: Login request validation

**Key Properties**:
- `Username string` - Username (validation: not empty)
- `Password string` - Password (validation: not empty)

**Key Methods**:
- `Validate() error` - Validates DTO fields

#### 7. Interfaces

**File**: `internal/application/interfaces/item_repository.go`
**Purpose**: Repository interface for item persistence

**Key Methods**:
- `Save(ctx context.Context, item *ItemEntity) error`
- `FindByID(ctx context.Context, id ItemID) (*ItemEntity, error)`
- `FindByUserID(ctx context.Context, userID UserID) ([]*ItemEntity, error)`
- `FindWhere(ctx context.Context, spec Specification[ItemEntity]) ([]*ItemEntity, error)`
- `Delete(ctx context.Context, id ItemID) error`
- `Exists(ctx context.Context, id ItemID) (bool, error)`

**File**: `internal/application/interfaces/user_repository.go`
**Purpose**: Repository interface for user persistence

**Key Methods**:
- `FindByUsername(ctx context.Context, username string) (*UserEntity, error)`
- `FindByID(ctx context.Context, id UserID) (*UserEntity, error)`
- `Save(ctx context.Context, user *UserEntity) error`

**File**: `internal/application/interfaces/auth_service.go`
**Purpose**: Authentication service interface

**Key Methods**:
- `Authenticate(ctx context.Context, username string, password string) (string, error)`
- `ValidateToken(ctx context.Context, token string) (bool, error)`
- `GetUserIDFromToken(ctx context.Context, token string) (string, error)`

**File**: `internal/application/interfaces/order_service.go`
**Purpose**: Order service interface

**Key Methods**:
- `OrderItem(ctx context.Context, item *ItemEntity) error`

**File**: `internal/application/interfaces/time_provider.go`
**Purpose**: Time provider interface for testing

**Key Methods**:
- `Now() time.Time`

**File**: `internal/application/interfaces/logger.go`
**Purpose**: Logger interface

**Key Methods**:
- `Info(ctx context.Context, msg string, fields ...interface{})`
- `Error(ctx context.Context, msg string, fields ...interface{})`
- `Debug(ctx context.Context, msg string, fields ...interface{})`
- `Warn(ctx context.Context, msg string, fields ...interface{})`

### Infrastructure Layer

#### 8. Repositories

**File**: `internal/infrastructure/repositories/file_item_repository.go`
**Purpose**: File-based implementation of item repository using JSON files

**Key Methods**:
- `Save(ctx context.Context, item *ItemEntity) error` - Persists item entity
- `FindByID(ctx context.Context, id ItemID) (*ItemEntity, error)` - Finds by ID
- `FindByUserID(ctx context.Context, userID UserID) ([]*ItemEntity, error)` - Finds by user
- `FindWhere(ctx context.Context, spec Specification[ItemEntity]) ([]*ItemEntity, error)` - Finds by specification using `ItemExpirationSpec`
- `Delete(ctx context.Context, id ItemID) error` - Deletes item
- `Exists(ctx context.Context, id ItemID) (bool, error)` - Checks existence

**Place in the flow**:
- Called by all commands and queries for data persistence and retrieval
- Uses `ItemExpirationSpec` for finding expired items

**File**: `internal/infrastructure/repositories/file_user_repository.go`
**Purpose**: File-based implementation of user repository using JSON files

**Key Methods**:
- `FindByUsername(ctx context.Context, username string) (*UserEntity, error)` - Finds by username
- `FindByID(ctx context.Context, id UserID) (*UserEntity, error)` - Finds by ID
- `Save(ctx context.Context, user *UserEntity) error` - Saves user

#### 9. HTTP Services

**File**: `internal/infrastructure/http/order_http_service.go`
**Purpose**: HTTP implementation of order service

**Key Methods**:
- `NewOrderHTTPService(client *http.Client, logger ILogger) *OrderHTTPService` - Constructor with dependency injection
- `OrderItem(ctx context.Context, item *ItemEntity) error` - Sends POST request to order URL

**Place in the flow**:
- Called by `AddItemCommand.Execute()` for expired items
- Called by `HandleExpiredItemsCommand.Execute()` for batch processing

#### 10. Authentication

**File**: `internal/infrastructure/auth/jwt_auth_service.go`
**Purpose**: JWT implementation of authentication service

**Key Methods**:
- `NewJWTAuthService(userRepo IUserRepository, secretKey string, logger ILogger) *JWTAuthService` - Constructor with dependency injection
- `Authenticate(ctx context.Context, username string, password string) (string, error)` - Validates credentials and generates JWT
- `ValidateToken(ctx context.Context, token string) (bool, error)` - Validates JWT token
- `GetUserIDFromToken(ctx context.Context, token string) (string, error)` - Extracts user ID from token

**Place in the flow**:
- Called by `LoginUserCommand.Execute()` for user authentication
- Used by `JWTMiddleware` for route protection

#### 11. Time Provider

**File**: `internal/infrastructure/time/system_time_provider.go`
**Purpose**: System time implementation

**Key Methods**:
- `NewSystemTimeProvider() *SystemTimeProvider` - Constructor
- `Now() time.Time` - Returns current system time

#### 12. Logger

**File**: `internal/infrastructure/logging/standard_logger.go`
**Purpose**: Standard library logger implementation

**Key Methods**:
- `NewStandardLogger(writer io.Writer) *StandardLogger` - Constructor
- `Info(ctx context.Context, msg string, fields ...interface{})` - Logs info message
- `Error(ctx context.Context, msg string, fields ...interface{})` - Logs error message
- `Debug(ctx context.Context, msg string, fields ...interface{})` - Logs debug message
- `Warn(ctx context.Context, msg string, fields ...interface{})` - Logs warning message

### Presentation Layer

#### 13. Controllers

**File**: `internal/presentation/controllers/items_controller.go`
**Purpose**: REST API endpoints for item management

**Key Methods**:
- `NewItemsController(addItemCmd *AddItemCommand, getItemQry *GetItemQuery, listItemsQry *ListItemsQuery, deleteItemCmd *DeleteItemCommand, logger ILogger) *ItemsController` - Constructor with dependency injection
- `CreateItem(c *gin.Context)` - POST /items
- `GetItem(c *gin.Context)` - GET /items/:id
- `ListItems(c *gin.Context)` - GET /items
- `DeleteItem(c *gin.Context)` - DELETE /items/:id

**Flow**:
- Receives HTTP requests and validates input
- Calls appropriate commands/queries based on HTTP method
- Returns standardized responses with DTOs

**File**: `internal/presentation/controllers/auth_controller.go`
**Purpose**: Authentication endpoints

**Key Methods**:
- `NewAuthController(loginUserCmd *LoginUserCommand, logger ILogger) *AuthController` - Constructor with dependency injection
- `Login(c *gin.Context)` - POST /login

#### 14. Middleware

**File**: `internal/presentation/middleware/jwt_middleware.go`
**Purpose**: JWT authentication middleware

**Key Methods**:
- `NewJWTMiddleware(authService IAuthService, logger ILogger) *JWTMiddleware` - Constructor with dependency injection
- `Middleware() gin.HandlerFunc` - Returns gin middleware function

**Place in the flow**:
- Applied to all protected routes by Gin router group
- Uses `JWTAuthService` for token validation

#### 15. Server

**File**: `internal/presentation/server/server.go`
**Purpose**: HTTP server setup and configuration

**Key Methods**:
- `NewServer(config *Config, logger ILogger) *Server` - Constructor with dependency injection
- `Start() error` - Starts the HTTP server
- `SetupRoutes() *gin.Engine` - Sets up routes and middleware

### Background Processing

**File**: `internal/infrastructure/scheduler/expired_items_scheduler.go`
**Purpose**: Scheduled job for processing expired items using a ticker

**Key Methods**:
- `NewExpiredItemsScheduler(handleExpiredItemsCmd *HandleExpiredItemsCommand, logger ILogger) *ExpiredItemsScheduler` - Constructor with dependency injection
- `Start(ctx context.Context) error` - Starts the scheduler
- `Stop() error` - Stops the scheduler
- `processExpiredItems(ctx context.Context) error` - Processes expired items

**Flow**:
1. **On startup**: `processExpiredItems()` immediately calls `HandleExpiredItemsCommand.Execute()`
2. **Every minute**: Ticker triggers `processExpiredItems()` to process expired items
3. All methods use context for cancellation and error handling
4. Comprehensive logging for monitoring and debugging

**Configuration**:
- Uses `time.Ticker` for periodic execution
- Implements graceful shutdown with context cancellation
- Configurable interval (default: 1 minute)

### Dependency Injection

**File**: `internal/container/container.go`
**Purpose**: Dependency injection container setup

**Key Methods**:
- `NewContainer(config *Config) *Container` - Constructor
- `Initialize() error` - Initializes all dependencies
- `GetItemRepository() IItemRepository` - Returns item repository
- `GetUserRepository() IUserRepository` - Returns user repository
- `GetAuthService() IAuthService` - Returns auth service
- `GetOrderService() IOrderService` - Returns order service
- `GetTimeProvider() ITimeProvider` - Returns time provider
- `GetLogger() ILogger` - Returns logger
- `GetAddItemCommand() *AddItemCommand` - Returns add item command
- `GetHandleExpiredItemsCommand() *HandleExpiredItemsCommand` - Returns handle expired items command
- `GetDeleteItemCommand() *DeleteItemCommand` - Returns delete item command
- `GetLoginUserCommand() *LoginUserCommand` - Returns login user command
- `GetGetItemQuery() *GetItemQuery` - Returns get item query
- `GetListItemsQuery() *ListItemsQuery` - Returns list items query
- `GetItemsController() *ItemsController` - Returns items controller
- `GetAuthController() *AuthController` - Returns auth controller
- `GetJWTMiddleware() *JWTMiddleware` - Returns JWT middleware
- `GetExpiredItemsScheduler() *ExpiredItemsScheduler` - Returns expired items scheduler

### Configuration

**File**: `internal/config/config.go`
**Purpose**: Application configuration

**Key Properties**:
- `ServerPort int` - Server port
- `JWTSecret string` - JWT secret key
- `DataDirectory string` - Directory for data files
- `LogLevel string` - Log level
- `SchedulerInterval time.Duration` - Scheduler interval

**Key Methods**:
- `Load() (*Config, error)` - Loads configuration from environment variables
- `Validate() error` - Validates configuration

### Main Application

**File**: `cmd/main.go`
**Purpose**: Application entry point

**Key Methods**:
- `main()` - Main function
- `setupGracefulShutdown(server *Server, scheduler *ExpiredItemsScheduler)` - Sets up graceful shutdown

**Flow**:
1. Loads configuration
2. Initializes dependency container
3. Creates server and scheduler
4. Starts scheduler
5. Starts server
6. Sets up graceful shutdown

## Complete Flow Summary

### Item Creation Flow
```
POST /items
├── JWTMiddleware (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
```
Scheduler (every minute)
└── ExpiredItemsScheduler.processExpiredItems()
    └── 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
├── JWTMiddleware (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
6. **Context Propagation**: All methods accept context for cancellation, deadlines, and tracing
7. **Error Handling**: Comprehensive error handling with proper error types
8. **Configuration Management**: Environment-based configuration with validation

## Go-Specific Best Practices

1. **Package Organization**: Follow Go's standard package layout with `internal/` for private packages
2. **Error Handling**: Use Go's error handling pattern with proper error wrapping
3. **Context Usage**: Use context for cancellation, deadlines, and request-scoped values
4. **Interface Segregation**: Keep interfaces small and focused
5. **Naming Conventions**: Follow Go's naming conventions (camelCase for exported, camelCase for unexported)
6. **Pointer vs Value**: Use pointers for mutable state and large structs, values for immutable data
7. **Concurrency**: Use goroutines and channels for concurrent operations
8. **Testing**: Write comprehensive tests with table-driven tests
9. **Documentation**: Use Go's documentation comments for all exported types and functions
10. **Dependencies**: Use Go modules for dependency management

## Directory Structure

```
golang/
├── cmd/
│   └── main.go                 # Application entry point
├── internal/
│   ├── application/
│   │   ├── commands/           # Command handlers
│   │   ├── queries/            # Query handlers
│   │   ├── dto/                # Data transfer objects
│   │   └── interfaces/         # Application interfaces
│   ├── domain/
│   │   ├── entities/           # Domain entities
│   │   ├── value_objects/      # Value objects
│   │   └── specifications/     # Domain specifications
│   ├── infrastructure/
│   │   ├── repositories/       # Repository implementations
│   │   ├── http/               # HTTP services
│   │   ├── auth/               # Authentication services
│   │   ├── time/               # Time provider
│   │   ├── logging/            # Logger implementations
│   │   └── scheduler/          # Background scheduler
│   ├── presentation/
│   │   ├── controllers/        # HTTP controllers
│   │   ├── middleware/         # HTTP middleware
│   │   └── server/             # HTTP server
│   ├── config/
│   │   └── config.go           # Configuration
│   └── container/
│       └── container.go        # Dependency injection container
├── pkg/
│   └── specifications/         # Reusable specification patterns
├── data/                       # Data files (JSON)
├── docker/
│   ├── docker-compose.yml      # Docker compose
│   └── Dockerfile              # Docker image
├── go.mod                      # Go module file
├── go.sum                      # Go module checksums
└── README.md                   # Go implementation README
```

This implementation plan ensures consistent development regardless of the implementer, providing clear flow definitions and emphasizing `ItemExpirationSpec` as the centralized source for expiration logic, while following Go best practices and idioms.