Page 1 of 7
System Requirements Document (SRD)
Project Name: cool-automation
1. Introduction
The cool-automation project is designed to automate repetitive customs workflows for a South African customs clearing and forwarding business. The goal is to reduce manual work, prevent errors, and eliminate delays that result in demurrage and penalties. This document outlines the system requirements for developing a Python-based Robotic Process Automation (RPA) solution tailored to the unique needs of the industry and locale.
Lesley Ndlovu, as the project owner, has provided clear priorities and constraints to ensure the solution aligns with South African regulations, including POPIA compliance, and operates reliably on local Windows PCs.
Page 2 of 7
2. System Overview
The cool-automation system will consist of multiple bots designed to automate key workflows in customs clearing and freight forwarding. These bots will interact with various systems, including:
- SARS eFiling portal (CUSDEC, SAD500, CUSRES)
- Shipping line tracking websites (e.g., Maersk, MSC, CMA CGM)
- Microsoft Outlook for email communication
- Excel files for shipment data, tariff codes, and invoices
The system will prioritize resilience, modularity, and ease of use, ensuring it can handle unstable websites, session timeouts, and local data processing requirements.
3. Functional Requirements
Container Tracking Bot (HIGH PRIORITY)
- As a User, I should be able to input a list of container numbers and shipment details from an Excel or CSV file.
- As a User, I should be able to extract container statuses from shipping line tracking websites.
- As a User, I should receive email notifications sent directly to specific clients when a container status changes to “Discharged.”
- As a User, I should be able to log all container statuses to a local file (Excel or database) for audit purposes.
Page 3 of 7
Invoice Processing + Duty Calculation
- As a User, I should be able to extract data from PDF invoices using OCR.
- As a User, I should be able to map extracted data to a tariff table from Excel or CSV.
- As a User, I should be able to calculate duties and VAT based on the mapped data.
- As a User, I should be able to generate a structured Excel summary of the calculations.
- As a User, I should be able to email quotes to clients based on the calculated duties and VAT.
SARS Pre-fill Automation
- As a User, I should be able to populate fields in the SARS eFiling CUSDEC form using shipment data from an Excel sheet.
- As a User, I should be able to leave the final submission for human review.
- As a User, I should be able to take screenshots of the populated form for audit purposes.
CUSRES Monitoring Bot
- As a User, I should be able to log into SARS eFiling and check for new responses.
- As a User, I should receive email alerts sent directly to specific clients if a response is rejected, including the reason for rejection.
- As a User, I should be able to maintain a log history of all responses for future reference.
4. User Personas
Admin
- Responsible for overseeing the automation system and ensuring compliance with POPIA regulations.
- Manages system configurations and updates.
Page 4 of 7
User
- Customs clearing agents who interact with the bots for daily operations.
- Inputs shipment data and reviews outputs.
Client
- Receives email notifications about container statuses and quotes.
- Relies on accurate and timely updates for decision-making.
5. Visuals Colors and Theme
Color Palette
The cool-automation project will use a professional and modern color palette inspired by the customs and freight forwarding industry:
- Background: #F5F5F5 (Light Gray)
- Surface: #FFFFFF (White)
- Text: #333333 (Dark Charcoal)
- Accent: #0077CC (Deep Blue)
- Muted Tones: #B0BEC5 (Soft Steel Gray)
6. Signature Design Concept
Concept: Interactive Freight Dashboard
The homepage will feature an Interactive Freight Dashboard that visually represents the automation system's workflows.
Page 5 of 7
Key Features:
- Dynamic Shipment Map: A live map showing container locations and statuses, with interactive pins users can click to view details.
- Workflow Animations: Animated flowcharts illustrating the automation process (e.g., container tracking, invoice processing).
- Client Portal: A section where clients can log in to view their shipment updates and quotes in real-time.
- Micro-Interactions: Hover effects on buttons and icons that provide tooltips or quick previews of data.
This design will make the system visually engaging while providing users and clients with intuitive access to critical information.
7. Non-Functional Requirements
- Reliability: The system must handle website changes, timeouts, and login failures gracefully.
- Scalability: Modular design to allow easy addition of new bots or workflows.
- Compliance: Ensure POPIA compliance by processing sensitive data locally.
- Performance: Must operate efficiently on a standard Windows PC without causing system slowdowns.
8. Tech Stack
Frontend
Backend
Page 6 of 7
Database
- MySQL or MariaDB (preferred for structured data)
AI Models
- GPT 5.4 for user-friendly responses
- Claude 4.6 Opas for academic or coding work
AI Tools
Local Orchestration
9. Assumptions and Constraints
Assumptions
- All input files (Excel, CSV, PDF) will be formatted consistently.
- Clients will provide accurate email addresses for notifications.
Constraints
- The system must run on local Windows PCs.
- Sensitive data must not be sent to external cloud services.
Page 7 of 7
10. Glossary
- POPIA: Protection of Personal Information Act, South Africa’s data privacy law.
- CUSDEC: Customs Declaration form used in SARS eFiling.
- CUSRES: Customs Response messages from SARS eFiling.
- Demurrage: Charges incurred for delays in container clearance.
- OCR: Optical Character Recognition, used for extracting text from images or PDFs.
No comments yet. Be the first!