System Requirements Document (SRD)

Project Name: Eagle-Manifest

1. Introduction

The Eagle-Manifest project is a logistics and transport management system designed to streamline the handling of manifests, declarations, invoices, and invoice line items. The system leverages OCR (Optical Character Recognition) technology to extract and validate data, ensuring compliance with strict business rules and maintaining data integrity.

This document outlines the updated system requirements for Eagle-Manifest, incorporating the pre-resolved changes authorized by the API supervisor. The system is tailored for Lesley Ndlovu's operational context in South Africa (ZA), adhering to locale-specific defaults such as currency (ZAR) and timezone (SAST).

2. System Overview

Eagle-Manifest operates as a hierarchical logistics management system with the following structure:

1. Manifest: Represents a single physical movement (truck, vessel, flight, train).
2. Declarations: Multiple declarations can exist within a single manifest.
3. Invoices: Each declaration can contain multiple invoices.
4. Invoice Line Items: Each invoice can contain multiple product lines.

The system integrates OCR technology to extract raw data from physical or digital documents, validate it against predefined rules, and map it to existing database tables. It also includes an intervention mode for handling incomplete or invalid data, ensuring smooth pipeline operations without fatal errors.

3. Functional Requirements

As User:

• As User, I should be able to upload manifests for OCR processing.
• As User, I should be able to view validation errors for mismatched unit prices immediately.
• As User, I should be able to trigger intervention mode for incomplete data.
• As User, I should be able to view hierarchical data structures (manifest → declarations → invoices → invoice lines).

As Admin:

• As Admin, I should be able to configure validation rules for unit prices globally.
• As Admin, I should be able to monitor OCR processing logs and pipeline performance.
• As Admin, I should be able to approve or reject intervention mode submissions.

4. User Personas

1. Admin

• Role: System administrator responsible for configuration, monitoring, and approvals.
• Key Tasks: Configure validation rules, monitor logs, approve/reject intervention submissions.

2. User

• Role: Operational user responsible for uploading manifests and managing data.
• Key Tasks: Upload manifests, view validation errors, trigger intervention mode, review hierarchical data.

5. Visuals Colors and Theme

Color Palette

The Eagle-Manifest system will feature a bold and professional color palette inspired by the logistics and transport industry:

• Background: #F4F4F9 (Soft Gray)
• Surface: #FFFFFF (Pure White)
• Text: #1A1A1D (Deep Charcoal)
• Accent: #0077B6 (Ocean Blue)
• Muted Tones: #A8A8B3 (Neutral Gray)

This palette ensures clarity, professionalism, and ease of use, while the accent color adds a touch of vibrancy.

6. Signature Design Concept

Interactive Manifest Journey

The homepage will feature an animated logistics journey map. Users will see a dynamic visualization of a transport route (e.g., truck, vessel, flight, train) moving across a stylized map of South Africa.

• Animation: The transport vehicle will move along the route, stopping at key points to highlight manifests, declarations, invoices, and line items.
• Interaction: Users can click on each stop to view hierarchical data in an expanding card format.
• Transitions: Smooth zoom-in and fade effects will guide users through the journey.
• Micro-interactions: Hovering over elements will display tooltips with additional information (e.g., manifest reference, transport type).
• Color Shifts: The map background will subtly shift colors based on the time of day (e.g., sunrise tones in the morning, twilight hues in the evening).

This concept creates an unforgettable first impression, immersing users in the logistics workflow while maintaining functionality and clarity.

7. Non-Functional Requirements

• Performance: The system must process OCR data within 5 seconds per document.
• Scalability: Support up to 10,000 manifests per month.
• Availability: Ensure 99.9% uptime.
• Security: Implement role-based access control (RBAC) and encrypt sensitive data.
• Localization: Default to South African Rand (ZAR) and South Africa Standard Time (SAST).

8. Tech Stack

Frontend

• React for Web

Backend

• Python
• FastAPI

Database

• MySQL or MariaDB (with Alembic for migrations)

AI Models

• GPT 5.4 for user-friendly responses

AI Tools

• Litellm for LLM Routing
• Langchain

Local Orchestration

• Docker
• docker-compose

Server-Side Orchestration

• Kubernetes

9. Assumptions and Constraints

Assumptions

• Users will upload manifests in supported formats (e.g., PDF, JPEG).
• All manifests will adhere to the hierarchical structure outlined in the system overview.
• The OCR engine will have access to pre-existing database schemas.

Constraints

• The system must not create or assume new database tables.
• Validation rules must strictly enforce global unit price consistency.
• Intervention mode must handle incomplete data without disrupting the pipeline.

10. Glossary

• Manifest: A record representing a single physical movement (e.g., truck, vessel, flight, train).
• Declaration: A document containing multiple invoices within a manifest.
• Invoice: A document containing multiple product lines within a declaration.
• Invoice Line Item: A single product line within an invoice.
• OCR: Optical Character Recognition, a technology for extracting text from images or scanned documents.
• Intervention Mode: A system state triggered when OCR data is incomplete or invalid, requiring human input.

End of Document