# sunil3140/vessel-report-validator architecture

> Architecture diagram of the GitHub repository sunil3140/vessel-report-validator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sunil3140/vessel-report-validator
- Repository: https://github.com/sunil3140/vessel-report-validator

## Overview

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`](https://github.com/sunil3140/vessel-report-validator/blob/main/app.py) (app.py), [`README.md`](https://github.com/sunil3140/vessel-report-validator/blob/main/README.md) (README), [`requirements.txt`](https://github.com/sunil3140/vessel-report-validator/blob/main/requirements.txt) (requirements), [`.devcontainer/devcontainer.json`](https://github.com/sunil3140/vessel-report-validator/blob/main/.devcontainer/devcontainer.json) (devcontainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Streamlit Runtime"]
  node_app["app.py<br/>Streamlit app<br/>[app.py]"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_deps["requirements<br/>python deps<br/>[requirements.txt]"]
  node_devcontainer["devcontainer<br/>dev env<br/>[devcontainer.json]"]
end

subgraph group_ui["Control Plane"]
  node_upload_ui(("Upload UI<br/>streamlit input"))
  node_smtp_ui(("SMTP UI<br/>config form"))
end

subgraph group_ingest["Ingestion"]
  node_report_xlsx[("Reports Excel<br/>input workbook")]
  node_mapping_file["Vessel Map<br/>recipient mapping"]
  node_parse_norm["Parse Sheet<br/>tabular ingest"]
end

subgraph group_validate["Validation Pipeline"]
  node_metrics["Derived Metrics<br/>feature calc"]
  node_rules{{"Rule Checks<br/>validation engine"}}
  node_failures[("Failure Reasons<br/>annotated results")]
end

subgraph group_output["Results and Delivery"]
  node_summary_chart(("Reason Chart<br/>analytics view"))
  node_failed_table[("Failed Table<br/>review table")]
  node_excel_export["Failed XLSX<br/>export file"]
  node_email_send["Email Sender<br/>smtp client"]
  node_smtp_server(("SMTP Server<br/>external mail"))
end

node_readme -->|"documents"| node_app
node_deps -->|"installs"| node_app
node_devcontainer -.->|"configures"| node_app
node_app -->|"renders"| node_upload_ui
node_app -->|"renders"| node_smtp_ui
node_upload_ui -->|"accepts"| node_report_xlsx
node_upload_ui -->|"accepts"| node_mapping_file
node_report_xlsx -->|"loads"| node_parse_norm
node_parse_norm -->|"enriches"| node_metrics
node_metrics -->|"feeds"| node_rules
node_rules -->|"marks"| node_failures
node_failures -->|"shows"| node_failed_table
node_failures -->|"summarizes"| node_summary_chart
node_failures -->|"exports"| node_excel_export
node_mapping_file -.->|"recipients"| node_email_send
node_smtp_ui -->|"configures"| node_email_send
node_excel_export -->|"attaches"| node_email_send
node_email_send -->|"delivers"| node_smtp_server

click node_app "https://github.com/sunil3140/vessel-report-validator/blob/main/app.py"
click node_readme "https://github.com/sunil3140/vessel-report-validator/blob/main/README.md"
click node_deps "https://github.com/sunil3140/vessel-report-validator/blob/main/requirements.txt"
click node_devcontainer "https://github.com/sunil3140/vessel-report-validator/blob/main/.devcontainer/devcontainer.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_readme,node_deps,node_devcontainer toneBlue
class node_upload_ui,node_smtp_ui toneAmber
class node_report_xlsx,node_mapping_file,node_parse_norm toneMint
class node_metrics,node_rules,node_failures toneRose
class node_summary_chart,node_failed_table,node_excel_export,node_email_send,node_smtp_server toneIndigo
```

## Components

### Streamlit Runtime

Single-process Python app and its supporting project files.

- [app.py](https://github.com/sunil3140/vessel-report-validator/blob/main/app.py): Streamlit app · Main application entrypoint containing UI, validation, export, and email orchestration. · `app.py`
- [README](https://github.com/sunil3140/vessel-report-validator/blob/main/README.md): docs · Documents inputs, outputs, validation behavior, and email workflow. · `README.md`
- [requirements](https://github.com/sunil3140/vessel-report-validator/blob/main/requirements.txt): python deps · Pinned runtime dependencies for Streamlit, pandas, numpy, and Excel handling. · `requirements.txt`
- [devcontainer](https://github.com/sunil3140/vessel-report-validator/blob/main/.devcontainer/devcontainer.json): dev env · Containerized development setup for reproducible local execution. · `.devcontainer/devcontainer.json`

### Control Plane

User actions and configuration exposed through Streamlit.

- **Upload UI**: streamlit input · Controls for uploading the report workbook and optional vessel-email mapping.
- **SMTP UI**: config form · Sidebar configuration for mail host, credentials, sender, and related delivery settings.

### Ingestion

Uploaded files and normalization into tabular data.

- **Reports Excel**: input workbook · Uploaded Excel file containing the canonical 'All Reports' sheet.
- **Vessel Map**: recipient mapping · Optional Excel or CSV file mapping vessels to recipient email addresses.
- **Parse Sheet**: tabular ingest · 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**: feature calc · Computes report hours, SFOC, and SCOC used by downstream rules and outputs.
- **Rule Checks**: validation engine · Applies domain checks for speed, exhaust temperature, running hours, auxiliaries, SFOC, and SCOC.
- **Failure Reasons**: annotated results · Rows that violate one or more rules, annotated with the specific failure reasons.

### Results and Delivery

Review surfaces, exports, and email notifications.

- **Reason Chart**: analytics view · Bar chart showing the frequency of validation failure reasons.
- **Failed Table**: review table · Interactive table of failed vessel reports for operator review.
- **Failed XLSX**: export file · Excel export containing failed rows and computed fields for offline review.
- **Email Sender**: smtp client · Composes messages and sends failed-report attachments to one vessel or many.
- **SMTP Server**: external mail · Gmail, Outlook, or Office 365 SMTP endpoint used for delivery.

## Connections

- 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.
