# usrr961/mpsd_awards architecture

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

- Interactive diagram: https://gitdiagram.com/usrr961/mpsd_awards
- Repository: https://github.com/usrr961/mpsd_awards
- Video tour (about a minute): https://gitdiagram.com/usrr961/mpsd_awards/video

## Overview

This is a Community Service Awards manager for tracking student service hours and awards. Staff use the desktop dashboard to import rosters and form responses, review calculated awards, manage Owl nominations and overrides, and prepare communications and exports. A LAN portal supports shared review and award overrides. The database is the shared state layer. Edges reflect sampled imports, calls, and documented module references; several dashboard and portal internals were only partially excerpted, so their detailed routes are not expanded.

Main entry points: [`pyqt_dashboard.py`](https://github.com/usrr961/mpsd_awards/blob/main/pyqt_dashboard.py) (Desktop Dashboard), [`database.py`](https://github.com/usrr961/mpsd_awards/blob/main/database.py) (Awards Database), [`email_dispatcher.py`](https://github.com/usrr961/mpsd_awards/blob/main/email_dispatcher.py) (Email Dispatch), [`importer.py`](https://github.com/usrr961/mpsd_awards/blob/main/importer.py) (Hours and Forms Import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Staff Workflow"]
  node_dashboard["Desktop Dashboard<br/>[pyqt_dashboard.py]"]
  node_roster_import["Roster Import<br/>[importer.py]"]
  node_service_import["Hours and Forms Import<br/>[importer.py]"]
  node_exports["Reports and Exports<br/>[pyqt_dashboard.py]"]
end

subgraph group_awards["Awards and Portal"]
  node_award_engine["Award Calculation<br/>[award_engine.py]"]
  node_owl_review["Owl Selection<br/>[web_server.py]"]
  node_portal["LAN Portal<br/>[web_server.py]"]
end

subgraph group_storage["Data Layer"]
  node_database[("Awards Database<br/>[database.py]")]
  node_configuration["Application Settings<br/>[config.py]"]
end

subgraph group_communications["Communications"]
  node_email["Email Dispatch"]
end

node_staff(("Staff"))
node_counselor(("Counselors"))
node_google_forms{{"Google Forms"}}
node_smtp{{"SMTP Service"}}
node_input_files["Import Files"]

node_staff -->|"uses"| node_dashboard
node_dashboard -->|"imports roster"| node_roster_import
node_dashboard -->|"imports responses"| node_service_import
node_input_files -.->|"provides roster"| node_roster_import
node_input_files -.->|"provides responses"| node_service_import
node_roster_import -->|"writes students"| node_database
node_service_import -->|"writes submissions"| node_database
node_dashboard -->|"calculates awards"| node_award_engine
node_award_engine -->|"reads and updates"| node_database
node_dashboard -->|"manages records"| node_database
node_dashboard -->|"starts portal"| node_portal
node_portal -->|"updates overrides"| node_database
node_portal -->|"selects Owl awards"| node_owl_review
node_dashboard -.->|"manages nominations"| node_owl_review
node_dashboard -->|"creates exports"| node_exports
node_dashboard -->|"prepares messages"| node_email
node_email -->|"reads settings"| node_configuration
node_email -->|"sends mail"| node_smtp
node_email -->|"requests writeup"| node_counselor
node_email -->|"links form"| node_google_forms
node_google_forms -.->|"returns responses"| node_service_import
node_database -->|"uses database URL"| node_configuration

click node_dashboard "https://github.com/usrr961/mpsd_awards/blob/main/pyqt_dashboard.py"
click node_roster_import "https://github.com/usrr961/mpsd_awards/blob/main/importer.py"
click node_service_import "https://github.com/usrr961/mpsd_awards/blob/main/importer.py"
click node_exports "https://github.com/usrr961/mpsd_awards/blob/main/pyqt_dashboard.py"
click node_award_engine "https://github.com/usrr961/mpsd_awards/blob/main/award_engine.py"
click node_owl_review "https://github.com/usrr961/mpsd_awards/blob/main/web_server.py"
click node_portal "https://github.com/usrr961/mpsd_awards/blob/main/web_server.py"
click node_database "https://github.com/usrr961/mpsd_awards/blob/main/database.py"
click node_configuration "https://github.com/usrr961/mpsd_awards/blob/main/config.py"
click node_email "https://github.com/usrr961/mpsd_awards/blob/main/email_dispatcher.py"

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_dashboard,node_roster_import,node_service_import,node_exports toneBlue
class node_award_engine,node_owl_review,node_portal toneAmber
class node_database,node_configuration toneMint
class node_email toneRose
class node_staff,node_counselor,node_google_forms,node_smtp,node_input_files toneIndigo
```

## Components

### Staff Workflow

- [Desktop Dashboard](https://github.com/usrr961/mpsd_awards/blob/main/pyqt_dashboard.py): `pyqt_dashboard.py`
- [Roster Import](https://github.com/usrr961/mpsd_awards/blob/main/importer.py): `importer.py`
- [Hours and Forms Import](https://github.com/usrr961/mpsd_awards/blob/main/importer.py): `importer.py`
- [Reports and Exports](https://github.com/usrr961/mpsd_awards/blob/main/pyqt_dashboard.py): `pyqt_dashboard.py`

### Awards and Portal

- [Award Calculation](https://github.com/usrr961/mpsd_awards/blob/main/award_engine.py): `award_engine.py`
- [Owl Selection](https://github.com/usrr961/mpsd_awards/blob/main/web_server.py): `web_server.py`
- [LAN Portal](https://github.com/usrr961/mpsd_awards/blob/main/web_server.py): `web_server.py`

### Data Layer

- [Awards Database](https://github.com/usrr961/mpsd_awards/blob/main/database.py): `database.py`
- [Application Settings](https://github.com/usrr961/mpsd_awards/blob/main/config.py): `config.py`

### Communications

- [Email Dispatch](https://github.com/usrr961/mpsd_awards/blob/main/email_dispatcher.py): `email_dispatcher.py`

### Other components

- **Staff**
- **Counselors**
- **Google Forms**
- **SMTP Service**
- **Import Files**

## Connections

- Staff → Desktop Dashboard: uses
- Desktop Dashboard → Roster Import: imports roster (evidence: `pyqt_dashboard.py`)
- Desktop Dashboard → Hours and Forms Import: imports responses (evidence: `pyqt_dashboard.py`)
- Import Files → Roster Import: provides roster
- Import Files → Hours and Forms Import: provides responses
- Roster Import → Awards Database: writes students (evidence: `importer.py`)
- Hours and Forms Import → Awards Database: writes submissions (evidence: `importer.py`)
- Desktop Dashboard → Award Calculation: calculates awards (evidence: `pyqt_dashboard.py`)
- Award Calculation → Awards Database: reads and updates (evidence: `award_engine.py`)
- Desktop Dashboard → Awards Database: manages records (evidence: `pyqt_dashboard.py`)
- Desktop Dashboard → LAN Portal: starts portal (evidence: `pyqt_dashboard.py`)
- LAN Portal → Awards Database: updates overrides (evidence: `web_server.py`)
- LAN Portal → Owl Selection: selects Owl awards (evidence: `web_server.py`)
- Desktop Dashboard → Owl Selection: manages nominations (evidence: `pyqt_dashboard.py`)
- Desktop Dashboard → Reports and Exports: creates exports (evidence: `pyqt_dashboard.py`)
- Desktop Dashboard → Email Dispatch: prepares messages (evidence: `pyqt_dashboard.py`)
- Email Dispatch → Application Settings: reads settings (evidence: `email_dispatcher.py`)
- Email Dispatch → SMTP Service: sends mail (evidence: `email_dispatcher.py`)
- Email Dispatch → Counselors: requests writeup (evidence: `email_dispatcher.py`)
- Email Dispatch → Google Forms: links form (evidence: `email_dispatcher.py`)
- Google Forms → Hours and Forms Import: returns responses
- Awards Database → Application Settings: uses database URL (evidence: `database.py`)
