# mec-osh/sama-yas architecture

> Architecture diagram of the GitHub repository mec-osh/sama-yas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mec-osh/sama-yas
- Repository: https://github.com/mec-osh/sama-yas

## Overview

#### Purpose and Entry Points
This is a GitHub Pages-ready Occupational Safety and Health (OSH) site for MEC’s Sama Yas project. It has three browser-delivered entry points:
- Public OSH portal: `index.html`, `app.js`
- Administrative dashboard: `admin/index.html`, `admin/admin.js`
- Risk assessment document generator: `risk-assessment/index.html`, `risk-assessment/app.js`

The application can operate as a local browser demo and is configured to connect to Supabase for shared live data.

#### Public OSH Portal
The public site presents bilingual English/Arabic OSH content, including RTL behavior, live man-hour and LTI-free-day calculations, safety performance, unsafe-act/condition trend data, document/news/gallery content, contacts, and anonymous safety concerns.
- `index.html`
- `app.js`
- `styles.css`

`app.js` is the primary public-page controller: it coordinates page interactions, local/demo state, public data presentation, and calculated operational indicators. Public reporting is intentionally separated from individual report records; public trend analysis exposes combined/baseline information rather than private report detail.

#### Admin Content and Operations Boundary
The admin prototype manages operational data that feeds public-facing sections: performance settings, safety reports, documents, news, galleries, locations, holidays, team profiles, contact content, and enquiries.
- `admin/index.html`
- `admin/admin.js`
- `supabase-config.js`

Admin access uses Supabase email OTP for the configured administrator. The browser client uses a publishable Supabase key; privileged writes, automatic email delivery, Microsoft Graph access, and secrets must remain behind Supabase Edge Functions or another secure backend.

#### Supabase Persistence and Security
Supabase is the central intended production backend for authentication, relational content/report data, Row-Level Security, and public/private Storage buckets.
- `supabase/schema.sql`
- `supabase/security-setup.sql`
- `SUPABASE_SETUP.txt`

Schema/setup scripts establish the core database and feature-specific additions. Root-level setup files such as `TREND_ANALYSIS_SETUP.sql`, `TEAM_MEMBERS_SETUP.sql`, and `CONTACT_SECTION_SETUP.sql` support incremental deployment, with corresponding versions under `supabase/`. Storage includes private report photos, accessed by admin export through short-lived signed URLs.

#### Safety Reporting and Trend Pipeline
Anonymous/public safety concerns and admin-managed safety reports form the reporting pipeline. In demo mode, entered data remains browser-local; live mode persists it to Supabase. Trend analysis combines a supplied historical baseline with newly recorded reports while retaining individual records as private.
- `app.js`
- `admin/admin.js`
- `TREND_ANALYSIS_SETUP.sql`

Admin export produces Excel-compatible reporting, including embedded photo thumbnails sourced from private storage. Email acknowledgements and report alerts are planned backend integrations rather than client-side direct sending.

#### Risk Assessment Generation
The standalone risk-assessment module loads a curated project risk-register dataset, lets users assemble and edit multiple activities, saves drafts in the browser, and generates a `.docx` assessment without an external document library.
- `risk-assessment/risk-register-data.js`
- `risk-assessment/legal-references.js`
- `risk-assessment/docx-generator.js`

Its flow is dataset selection → editable assessment state → risk/control and legal-reference enrichment → client-side Word document generation. Legal references preserve source references where available and add applicable ADOSH-SF and ALDAR references.

#### External Dependencies and Deployment
The runtime is static HTML/CSS/JavaScript hosted on GitHub Pages, with Supabase as the live service dependency.
- `README.md`
- `supabase-config.js`
- `assets/osh-team-organization-chart.pptx`

Operational integrations include Supabase Auth/Database/Storage, optional official UAE holiday data, and a future Microsoft Graph or secure mail-function integration. Direct Microsoft 365 sending is deliberately not embedded in the static site.

Main entry points: [`admin/admin.js`](https://github.com/mec-osh/sama-yas/blob/main/admin/admin.js) (Admin Controller), [`app.js`](https://github.com/mec-osh/sama-yas/blob/main/app.js) (Public Controller), [`risk-assessment/app.js`](https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/app.js) (Assessment Editor), [`README.md`](https://github.com/mec-osh/sama-yas/blob/main/README.md) (GitHub Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public Portal"]
  node_public_page["Public OSH Portal<br/>HTML entry<br/>[index.html]"]
  node_public_controller["Public Controller<br/>browser controller<br/>[app.js]"]
  node_public_styles["Portal Styles<br/>CSS<br/>[styles.css]"]
  node_public_trends["Public Trend View<br/>privacy-safe analytics<br/>[app.js]"]
end

subgraph group_admin["Admin Operations"]
  node_admin_page["Admin Dashboard<br/>HTML entry<br/>[index.html]"]
  node_admin_controller["Admin Controller<br/>browser controller<br/>[admin.js]"]
  node_supabase_client_config["Supabase Client Config<br/>browser configuration<br/>[supabase-config.js]"]
  node_admin_export["Excel Report Export<br/>client export<br/>[admin.js]"]
end

subgraph group_backend["Supabase Live Backend"]
  node_schema[("Core Schema<br/>SQL schema<br/>[schema.sql]")]
  node_security["RLS and Security Setup<br/>SQL security<br/>[security-setup.sql]"]
  node_trend_setup["Trend Baseline Setup<br/>SQL migration"]
  node_supabase_auth{{"Email OTP Auth<br/>Supabase Auth"}}
  node_supabase_data[("Content and Report Data<br/>Supabase Database")]
  node_private_storage[("Private Report Photos<br/>Supabase Storage")]
  node_secure_integrations{{"Secure Backend Integrations<br/>Edge Functions or backend"}}
end

subgraph group_risk["Risk Assessment"]
  node_risk_page["Risk Assessment UI<br/>HTML entry<br/>[index.html]"]
  node_risk_controller["Assessment Editor<br/>browser controller<br/>[app.js]"]
  node_risk_register["Risk Register Dataset<br/>curated dataset"]
  node_legal_refs["Legal Reference Enrichment<br/>reference dataset"]
  node_docx_generator["DOCX Generator<br/>client document generator<br/>[docx-generator.js]"]
end

node_pages{{"GitHub Pages<br/>static host<br/>[README.md]"}}

node_pages -->|"serves"| node_public_page
node_pages -->|"serves"| node_admin_page
node_pages -->|"serves"| node_risk_page
node_public_page -->|"runs"| node_public_controller
node_public_page -->|"styles"| node_public_styles
node_public_controller -->|"calculates and presents"| node_public_trends
node_public_controller -->|"reads live data or uses local demo state"| node_supabase_data
node_public_controller -->|"submits report photos in live mode"| node_private_storage
node_admin_page -->|"runs"| node_admin_controller
node_admin_controller -->|"uses"| node_supabase_client_config
node_admin_controller -->|"signs in with OTP"| node_supabase_auth
node_admin_controller -->|"manages operational content"| node_supabase_data
node_admin_controller -->|"produces"| node_admin_export
node_admin_export -->|"requests signed photo URLs"| node_private_storage
node_schema -->|"defines"| node_supabase_data
node_security -->|"protects with RLS"| node_supabase_data
node_trend_setup -->|"provides historical baseline"| node_public_trends
node_admin_controller -.->|"delegates privileged actions"| node_secure_integrations
node_risk_page -->|"runs"| node_risk_controller
node_risk_controller -->|"selects activities from"| node_risk_register
node_risk_controller -->|"enriches controls with"| node_legal_refs
node_risk_controller -->|"generates assessment with"| node_docx_generator

click node_pages "https://github.com/mec-osh/sama-yas/blob/main/README.md"
click node_public_page "https://github.com/mec-osh/sama-yas/blob/main/index.html"
click node_public_controller "https://github.com/mec-osh/sama-yas/blob/main/app.js"
click node_public_styles "https://github.com/mec-osh/sama-yas/blob/main/styles.css"
click node_public_trends "https://github.com/mec-osh/sama-yas/blob/main/app.js"
click node_admin_page "https://github.com/mec-osh/sama-yas/blob/main/admin/index.html"
click node_admin_controller "https://github.com/mec-osh/sama-yas/blob/main/admin/admin.js"
click node_supabase_client_config "https://github.com/mec-osh/sama-yas/blob/main/supabase-config.js"
click node_admin_export "https://github.com/mec-osh/sama-yas/blob/main/admin/admin.js"
click node_schema "https://github.com/mec-osh/sama-yas/blob/main/supabase/schema.sql"
click node_security "https://github.com/mec-osh/sama-yas/blob/main/supabase/security-setup.sql"
click node_trend_setup "https://github.com/mec-osh/sama-yas/blob/main/TREND_ANALYSIS_SETUP.sql"
click node_risk_page "https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/index.html"
click node_risk_controller "https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/app.js"
click node_risk_register "https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/risk-register-data.js"
click node_legal_refs "https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/legal-references.js"
click node_docx_generator "https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/docx-generator.js"

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_public_page,node_public_controller,node_public_styles,node_public_trends toneBlue
class node_admin_page,node_admin_controller,node_supabase_client_config,node_admin_export toneAmber
class node_schema,node_security,node_trend_setup,node_supabase_auth,node_supabase_data,node_private_storage,node_secure_integrations toneMint
class node_risk_page,node_risk_controller,node_risk_register,node_legal_refs,node_docx_generator toneRose
class node_pages toneNeutral
```

## Components

### Public Portal

- [Public OSH Portal](https://github.com/mec-osh/sama-yas/blob/main/index.html): HTML entry · `index.html`
- [Public Controller](https://github.com/mec-osh/sama-yas/blob/main/app.js): browser controller · Presents bilingual content, indicators, trends, and anonymous concerns. · `app.js`
- [Portal Styles](https://github.com/mec-osh/sama-yas/blob/main/styles.css): CSS · Provides English/Arabic and RTL presentation. · `styles.css`
- [Public Trend View](https://github.com/mec-osh/sama-yas/blob/main/app.js): privacy-safe analytics · Shows combined or baseline trend data, not individual reports. · `app.js`

### Admin Operations

- [Admin Dashboard](https://github.com/mec-osh/sama-yas/blob/main/admin/index.html): HTML entry · `admin/index.html`
- [Admin Controller](https://github.com/mec-osh/sama-yas/blob/main/admin/admin.js): browser controller · Manages operational content, reports, exports, and settings. · `admin/admin.js`
- [Supabase Client Config](https://github.com/mec-osh/sama-yas/blob/main/supabase-config.js): browser configuration · Uses a publishable client key only. · `supabase-config.js`
- [Excel Report Export](https://github.com/mec-osh/sama-yas/blob/main/admin/admin.js): client export · Builds Excel-compatible reports with signed private-photo access. · `admin/admin.js`

### Supabase Live Backend

- [Core Schema](https://github.com/mec-osh/sama-yas/blob/main/supabase/schema.sql): SQL schema · Defines relational content and report data. · `supabase/schema.sql`
- [RLS and Security Setup](https://github.com/mec-osh/sama-yas/blob/main/supabase/security-setup.sql): SQL security · Establishes access controls and feature setup. · `supabase/security-setup.sql`
- [Trend Baseline Setup](https://github.com/mec-osh/sama-yas/blob/main/TREND_ANALYSIS_SETUP.sql): SQL migration · Supplies historical baseline data for trend analysis. · `TREND_ANALYSIS_SETUP.sql`
- **Email OTP Auth**: Supabase Auth · Authenticates the configured administrator.
- **Content and Report Data**: Supabase Database · Stores live public content, operational data, and private reports.
- **Private Report Photos**: Supabase Storage · Serves admin exports through short-lived signed URLs.
- **Secure Backend Integrations**: Edge Functions or backend · Reserved for privileged writes, mail, alerts, and Microsoft Graph access.

### Risk Assessment

- [Risk Assessment UI](https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/index.html): HTML entry · `risk-assessment/index.html`
- [Assessment Editor](https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/app.js): browser controller · Maintains multi-activity editable state and browser drafts. · `risk-assessment/app.js`
- [Risk Register Dataset](https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/risk-register-data.js): curated dataset · `risk-assessment/risk-register-data.js`
- [Legal Reference Enrichment](https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/legal-references.js): reference dataset · Adds source, ADOSH-SF, and ALDAR references. · `risk-assessment/legal-references.js`
- [DOCX Generator](https://github.com/mec-osh/sama-yas/blob/main/risk-assessment/docx-generator.js): client document generator · Generates Word assessments without an external document library. · `risk-assessment/docx-generator.js`

### Other components

- [GitHub Pages](https://github.com/mec-osh/sama-yas/blob/main/README.md): static host · Hosts the browser-delivered site. · `README.md`

## Connections

- GitHub Pages → Public OSH Portal: serves
- GitHub Pages → Admin Dashboard: serves
- GitHub Pages → Risk Assessment UI: serves
- Public OSH Portal → Public Controller: runs
- Public OSH Portal → Portal Styles: styles
- Public Controller → Public Trend View: calculates and presents
- Public Controller → Content and Report Data: reads live data or uses local demo state
- Public Controller → Private Report Photos: submits report photos in live mode
- Admin Dashboard → Admin Controller: runs
- Admin Controller → Supabase Client Config: uses
- Admin Controller → Email OTP Auth: signs in with OTP
- Admin Controller → Content and Report Data: manages operational content
- Admin Controller → Excel Report Export: produces
- Excel Report Export → Private Report Photos: requests signed photo URLs
- Core Schema → Content and Report Data: defines
- RLS and Security Setup → Content and Report Data: protects with RLS
- Trend Baseline Setup → Public Trend View: provides historical baseline
- Admin Controller → Secure Backend Integrations: delegates privileged actions
- Risk Assessment UI → Assessment Editor: runs
- Assessment Editor → Risk Register Dataset: selects activities from
- Assessment Editor → Legal Reference Enrichment: enriches controls with
- Assessment Editor → DOCX Generator: generates assessment with