How sunil3140/vessel-report-validator works
1. Overall shape
- This repository is a single-page Streamlit application centered in app.py.
- The app ingests Excel report data, validates each vessel report against domain rules, presents the failures interactively, allows export, and can email results to operators.
2. Primary runtime boundary
- The app runs as a Python 3.8+ Streamlit process.
- Core libraries implied by the README are streamlit for UI, pandas for tabular processing, numpy for numeric calculations, and openpyxl for Excel read/write.
- There is no separate backend service, database, or queue layer in the repository structure.
3. Input ingestion boundary
- The main data source is an uploaded Excel file containing a sheet named All Reports.
- That sheet is the system’s canonical input schema and includes vessel identity, voyage timing, engine metrics, fuel/oil consumption, exhaust temperatures, and sub-consumer fields.
- A second optional input is a vessel-to-email mapping file in Excel or CSV for bulk notification.
4. Validation engine
- app.py implements a rules-based validation pipeline over each report row.
- The validation logic is domain-specific and divided into six checks: SFOC, average speed, exhaust temperature deviation, running-hours consistency, auxiliary-engine/sub-consumer consistency, and SCOC.
- Some rules are conditional on report type and operational context, such as “At Sea” reports and minimum main-engine running hours.
5. Derived metrics layer
- The app does not only compare raw values; it also computes intermediate metrics used by the rules.
- Key derived values are Report Hours, SFOC, and SCOC, calculated from dates/times and consumption/load/running-hour fields.
- These computed columns are also carried through to output artifacts so the validation results are explainable and auditable.
6. Failure aggregation and presentation
- The app produces a failed-reports table containing only rows that violate one or more rules.
- Each failed row is annotated with the reasons for failure, which serves as the main review surface for the operator.
- A bar chart summarizes the frequency of failure reasons, providing a lightweight analytics view over the validation output.
7. Export path
- Failed validation results can be exported as an Excel file named Failed_Validation.xlsx.
- The export includes the original failed rows plus the computed fields needed to interpret the failure.
- This makes the output portable for offline review or for forwarding to ship operators.
8. Notification subsystem
- The app supports two notification modes: single-vessel email and bulk email to all vessels.
- In bulk mode, the app uses the vessel-email mapping file to determine recipients per ship, including optional CC fields.
- The email content includes the failed report as an Excel attachment.
9. External service integration
- Email delivery is done through SMTP, with configuration provided in the Streamlit sidebar.
- The README calls out Gmail and Outlook/Office 365 as supported SMTP targets, which means the app is designed to integrate directly with standard mail infrastructure rather than a custom messaging service.
10. Operational/user interface boundary
- Streamlit acts as the presentation and control plane: upload files, select vessel, enter recipients, configure SMTP, and trigger validation or send actions.
- This keeps user interaction, data processing, and notification orchestration in one process, with no separate frontend/backend split.
11. Repository organization
- The repository is intentionally minimal: app.py contains the application logic, README.md documents behavior and input/output expectations, and requirements.txt captures dependencies.
- .devcontainer suggests a reproducible development environment for local or containerized setup, but it does not introduce a runtime subsystem.
12. Architecture takeaway
- For diagramming, model this repo as a single Streamlit application with three internal pipelines: file ingestion, validation/aggregation, and export/email delivery.
- The main external boundaries are the uploaded Excel/CSV files and the SMTP server; everything else is in-process Python logic.
Main entry points: app.py app.py · README.md README · requirements.txt requirements · devcontainer.json devcontainer
Components 17
Streamlit Runtime
Single-process Python app and its supporting project files.
- app.py · Main application entrypoint containing UI, validation, export, and email orchestration.
app.py - README · Documents inputs, outputs, validation behavior, and email workflow.
README.md - requirements · Pinned runtime dependencies for Streamlit, pandas, numpy, and Excel handling.
requirements.txt - devcontainer · Containerized development setup for reproducible local execution.
.devcontainer/devcontainer.json
Control Plane
User actions and configuration exposed through Streamlit.
- Upload UI · Controls for uploading the report workbook and optional vessel-email mapping.
- SMTP UI · Sidebar configuration for mail host, credentials, sender, and related delivery settings.
Ingestion
Uploaded files and normalization into tabular data.
- Reports Excel · Uploaded Excel file containing the canonical 'All Reports' sheet.
- Vessel Map · Optional Excel or CSV file mapping vessels to recipient email addresses.
- Parse Sheet · Loads the workbook, selects the report sheet, and normalizes rows into a dataframe.
Validation Pipeline
Derived metrics and rule checks that produce failures.
- Derived Metrics · Computes report hours, SFOC, and SCOC used by downstream rules and outputs.
- Rule Checks · Applies domain checks for speed, exhaust temperature, running hours, auxiliaries, SFOC, and SCOC.
- Failure Reasons · Rows that violate one or more rules, annotated with the specific failure reasons.
Results and Delivery
Review surfaces, exports, and email notifications.
- Reason Chart · Bar chart showing the frequency of validation failure reasons.
- Failed Table · Interactive table of failed vessel reports for operator review.
- Failed XLSX · Excel export containing failed rows and computed fields for offline review.
- Email Sender · Composes messages and sends failed-report attachments to one vessel or many.
- SMTP Server · Gmail, Outlook, or Office 365 SMTP endpoint used for delivery.
Connections 18
- README → app.py: documents · Repository behavior and workflow are described in the README.
- requirements → app.py: installs · Dependencies enable the Streamlit application runtime.
- devcontainer → app.py: configures · Provides a reproducible development environment for the app.
- app.py → Upload UI: renders · The app presents upload and configuration controls in Streamlit.
- app.py → SMTP UI: renders · The app exposes SMTP and sender settings in the sidebar.
- Upload UI → Reports Excel: accepts · Primary workbook upload enters the pipeline.
- Upload UI → Vessel Map: accepts · Optional vessel-to-email mapping file enters the pipeline.
- Reports Excel → Parse Sheet: loads · The workbook is read and the All Reports sheet is extracted.
- Parse Sheet → Derived Metrics: enriches · Parsed rows are augmented with computed report metrics.
- Derived Metrics → Rule Checks: feeds · Derived values and source fields drive the rule checks.
- Rule Checks → Failure Reasons: marks · Violating rows are collected with reasons for failure.
- Failure Reasons → Failed Table: shows · The failed-report table is the primary review surface.
- Failure Reasons → Reason Chart: summarizes · Failure reasons are aggregated into a frequency chart.
- Failure Reasons → Failed XLSX: exports · Failed rows plus computed fields are written to Excel.
- Vessel Map → Email Sender: recipients · Recipient lookup for bulk vessel notifications.
- SMTP UI → Email Sender: configures · SMTP settings are used by the mail sender.
- Failed XLSX → Email Sender: attaches · The failed-report workbook is attached to outbound email.
- Email Sender → SMTP Server: delivers · Messages are sent through a standard SMTP endpoint.