About this project
Stock-Titan is an enterprise-grade automation platform built with Python that solves the complex challenge of synchronizing automotive spare parts inventory from multiple suppliers to e-commerce platforms. The system handles the entire pipeline from FTP file download to data normalization, stock aggregation, platform inventory updates, and file upload.
The architecture follows Clean Architecture principles with DDD-inspired layering. The domain layer defines entities and value objects for products, quantities, and stock levels. The service layer implements pure business logic for normalization, aggregation, and update operations. The infrastructure layer handles external systems including FTP clients, file storage, and encoding detection. The orchestration layer coordinates the complete pipeline through tracked steps.
Configuration is managed through YAML files defining supplier FTP credentials, platform FTP connections, header mappings, and system settings. All configuration is validated through Pydantic models ensuring type safety and catching errors at startup. The system supports unlimited suppliers and platforms, each with their own file format conventions.
The data processing engine handles remarkable diversity in supplier file formats. It auto-detects file encoding using chardet with fallback options, identifies separators automatically (comma, semicolon, tab, pipe), normalizes European decimal formats, preserves product IDs with special characters, and handles non-standard quantity representations like '>10', 'LOW', and '<5'. Column mapping supports both name-based and index-based matching with fuzzy logic for encoding-related mismatches.
The pipeline orchestrates nine sequential steps: download supplier files, download platform files, read and normalize supplier data, aggregate stock across all suppliers, read platform files, update platform inventories, write updated files preserving original format, upload to platform FTP servers, and cleanup temporary files. Each step is tracked with timing and statistics in an execution context.
The system was refactored from a 5,000+ line monolithic codebase into a clean 2,500-line architecture with zero code duplication, 100% type safety, and comprehensive test coverage. An enterprise testing framework with 81 tests ensures reliability across all file formats, encodings, and edge cases — including regression tests for known bugs. Docker support enables scheduled automated runs in production environments.
