# jocelyncheruel/narval-plus architecture

> Architecture diagram of the GitHub repository jocelyncheruel/narval-plus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jocelyncheruel/narval-plus
- Repository: https://github.com/jocelyncheruel/narval-plus

## Overview

Narval+ is a Chrome extension that overlays student results on the Narval portal. The main workflow is to load the portal, read and present academic results, and retain local state; optional branches provide community rankings, device management, and extension-update notices. The sampled implementation is concentrated in content.js, so several internal responsibilities are modeled separately but share that path. The README documents capabilities whose internal call paths were not sampled; those links are shown as unverified where appropriate.

Main entry points: [`content.js`](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js) (Extension overlay), [`config.js`](https://github.com/jocelyncheruel/narval-plus/blob/main/config.js) (Update settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Portal experience"]
  node_narval["Narval portal"]
  node_overlay["Extension overlay<br/>[content.js]"]
  node_local_state[("Local state<br/>[content.js]")]
end

subgraph group_academic["Academic results"]
  node_parser["Results parser<br/>[content.js]"]
  node_academic_model["Academic model<br/>[content.js]"]
  node_dashboard["Results dashboard<br/>[content.js]"]
  node_periods["Period views<br/>[content.js]"]
end

subgraph group_community["Community ranking"]
  node_ranking_ui["Ranking controls<br/>[content.js]"]
  node_identity_devices["Identity and devices<br/>[content.js]"]
  node_ranking_client["Ranking client<br/>[content.js]"]
  node_ranking_service["Ranking service"]
end

subgraph group_maintenance["Updates"]
  node_update_checker["Update checker<br/>[content.js]"]
  node_update_notice["Update notice<br/>[content.js]"]
  node_update_config["Update settings<br/>[config.js]"]
  node_download["ZIP download"]
end

node_student(("Student"))
node_chrome["Chrome"]

node_student -->|"opens"| node_narval
node_narval -.->|"loads alongside"| node_overlay
node_chrome -.->|"hosts extension"| node_overlay
node_overlay -->|"reads and writes"| node_local_state
node_overlay -->|"starts check"| node_update_checker
node_overlay -->|"initializes when enabled"| node_identity_devices
node_student -->|"enables participation"| node_ranking_ui
node_ranking_ui -.->|"requests rankings"| node_ranking_client
node_ranking_client -.->|"exchanges aggregates"| node_ranking_service
node_identity_devices -.->|"links or revokes devices"| node_ranking_service
node_student -->|"manages devices"| node_identity_devices
node_update_checker -->|"shows notice"| node_update_notice
node_update_config -.->|"sets endpoints"| node_update_checker
node_student -->|"downloads update"| node_download
node_update_notice -->|"links to ZIP"| node_download
node_dashboard -.->|"offers selection"| node_periods
node_overlay -.->|"extracts portal data"| node_parser
node_parser -.->|"builds results"| node_academic_model
node_academic_model -.->|"supplies results"| node_dashboard

click node_overlay "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_parser "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_academic_model "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_dashboard "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_periods "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_local_state "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_ranking_ui "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_identity_devices "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_ranking_client "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_update_checker "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_update_notice "https://github.com/jocelyncheruel/narval-plus/blob/main/content.js"
click node_update_config "https://github.com/jocelyncheruel/narval-plus/blob/main/config.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_narval,node_overlay,node_local_state toneBlue
class node_parser,node_academic_model,node_dashboard,node_periods toneAmber
class node_ranking_ui,node_identity_devices,node_ranking_client,node_ranking_service toneMint
class node_update_checker,node_update_notice,node_update_config,node_download toneRose
class node_student,node_chrome toneIndigo
```

## Components

### Portal experience

- **Narval portal**
- [Extension overlay](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Local state](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`

### Academic results

- [Results parser](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Academic model](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Results dashboard](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Period views](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`

### Community ranking

- [Ranking controls](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Identity and devices](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Ranking client](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- **Ranking service**

### Updates

- [Update checker](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Update notice](https://github.com/jocelyncheruel/narval-plus/blob/main/content.js): `content.js`
- [Update settings](https://github.com/jocelyncheruel/narval-plus/blob/main/config.js): `config.js`
- **ZIP download**

### Other components

- **Student**
- **Chrome**

## Connections

- Student → Narval portal: opens (evidence: `README.md`)
- Narval portal → Extension overlay: loads alongside
- Chrome → Extension overlay: hosts extension
- Extension overlay → Local state: reads and writes (evidence: `content.js`)
- Extension overlay → Update checker: starts check (evidence: `content.js`)
- Extension overlay → Identity and devices: initializes when enabled (evidence: `content.js`)
- Student → Ranking controls: enables participation (evidence: `README.md`)
- Ranking controls → Ranking client: requests rankings (evidence: `content.js`)
- Ranking client → Ranking service: exchanges aggregates
- Identity and devices → Ranking service: links or revokes devices
- Student → Identity and devices: manages devices (evidence: `README.md`)
- Update checker → Update notice: shows notice (evidence: `README.md`)
- Update settings → Update checker: sets endpoints
- Student → ZIP download: downloads update (evidence: `README.md`)
- Update notice → ZIP download: links to ZIP (evidence: `README.md`)
- Results dashboard → Period views: offers selection (evidence: `content.js`)
- Extension overlay → Results parser: extracts portal data (evidence: `content.js`)
- Results parser → Academic model: builds results (evidence: `content.js`)
- Academic model → Results dashboard: supplies results (evidence: `content.js`)
