# ngtruongmetin/twd_hpd architecture

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

- Interactive diagram: https://gitdiagram.com/ngtruongmetin/twd_hpd
- Repository: https://github.com/ngtruongmetin/twd_hpd

## Overview

This is a competition-submission and judging platform with a React role-based portal and an Express/SQLite API. Users register or sign in, submit and manage entries, judges score them, administrators manage seasons and competition data, and public users can look up results; administrators also handle voting metrics and exports. The graph follows documented routing and sampled controller/service calls. Several feature paths are visible only in the tree or route index, so their internal links are omitted or marked unverified.

Main entry points: [`backend/utils/db.js`](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/utils/db.js) (SQLite database), [`backend/server.js`](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/server.js) (HTTP server), [`frontend/src/App.tsx`](https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/App.tsx) (Route shell), [`backend/controllers/ExportController.js`](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/ExportController.js) (Exports and statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Web portal"]
  node_app["Route shell<br/>[App.tsx]"]
  node_authui["Auth state<br/>[AuthContext.tsx]"]
  node_entryui["Entry workspace<br/>[Submissions.tsx]"]
  node_judgeui["Judge workspace<br/>[Submissions.tsx]"]
  node_adminui["Admin workspaces<br/>[Submissions.tsx]"]
  node_lookupui["Public lookup"]
end

subgraph group_api["API and access"]
  node_server["HTTP server<br/>[server.js]"]
  node_auth["Session authorization<br/>[AuthMiddleware.js]"]
  node_authctl["Account access<br/>[AuthController.js]"]
end

subgraph group_competition["Competition workflow"]
  node_submissions["Submission handling"]
  node_judging["Judge scoring"]
  node_results["Result finalization"]
  node_scorecalc["Score totals"]
  node_complaints["Complaint messaging"]
  node_voting["Voting metrics"]
end

subgraph group_operations["Administration and reporting"]
  node_adminctl["Central administration"]
  node_techadmin["Technical administration"]
  node_resources["Resource management"]
  node_exports["Exports and statistics"]
  node_publiclookup["Public lookup API"]
end

subgraph group_persistence["Storage and integrations"]
  node_db[("SQLite database<br/>[db.js]")]
  node_mail["Mail delivery<br/>[mailer.js]"]
  node_drive["Google Drive<br/>[google.js]"]
  node_datamodel["Export formatting<br/>[DataModel.js]"]
end

node_visitor(("Portal users"))

node_visitor -->|"uses portal"| node_app
node_app -->|"provides auth"| node_authui
node_app -->|"routes contestants"| node_entryui
node_app -->|"routes judges"| node_judgeui
node_app -->|"routes admins"| node_adminui
node_app -->|"routes lookup"| node_lookupui
node_entryui -.->|"requests API"| node_server
node_judgeui -.->|"requests API"| node_server
node_adminui -.->|"requests API"| node_server
node_lookupui -.->|"requests API"| node_server
node_server -->|"protects routes"| node_auth
node_server -->|"routes submissions"| node_submissions
node_server -->|"routes scores"| node_judging
node_server -->|"routes admin"| node_adminctl
node_server -->|"initializes schema"| node_db
node_submissions -->|"reads and writes"| node_db
node_judging -->|"calculates totals"| node_scorecalc
node_judging -->|"reads and writes"| node_db
node_results -->|"calculates totals"| node_scorecalc
node_results -->|"reads and writes"| node_db
node_adminctl -->|"uses metrics"| node_voting
node_adminctl -->|"reads and writes"| node_db
node_exports -->|"queries data"| node_db
node_exports -->|"formats export"| node_datamodel
node_exports -->|"loads provinces"| node_db
node_resources -->|"manages records"| node_db
node_publiclookup -->|"queries entries"| node_db
node_authctl -->|"reads and writes"| node_db
node_authctl -->|"sends messages"| node_mail
node_submissions -.->|"checks Drive links"| node_drive
node_complaints -.->|"stores messages"| node_db

click node_app "https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/context/AuthContext.tsx"
click node_entryui "https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/contestant/Submissions.tsx"
click node_judgeui "https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/judge/Submissions.tsx"
click node_adminui "https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/tw_admin/Submissions.tsx"
click node_lookupui "https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/LookupSubmissions.tsx"
click node_server "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/server.js"
click node_auth "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/middlewares/AuthMiddleware.js"
click node_authctl "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/AuthController.js"
click node_submissions "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/SubmissionController.js"
click node_judging "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/JudgeScoreController.js"
click node_results "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/SubmissionResultController.js"
click node_scorecalc "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/services/ScoreTotalService.js"
click node_complaints "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/ComplaintController.js"
click node_voting "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/services/VoteMetricsService.js"
click node_adminctl "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/TwAdminController.js"
click node_techadmin "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/TechAdminController.js"
click node_resources "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/ResourceController.js"
click node_exports "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/ExportController.js"
click node_publiclookup "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/PublicLookupController.js"
click node_db "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/utils/db.js"
click node_mail "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/utils/mailer.js"
click node_drive "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/utils/google.js"
click node_datamodel "https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/models/DataModel.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_app,node_authui,node_entryui,node_judgeui,node_adminui,node_lookupui,node_visitor toneBlue
class node_server,node_auth,node_authctl toneAmber
class node_submissions,node_judging,node_results,node_scorecalc,node_complaints,node_voting toneMint
class node_adminctl,node_techadmin,node_resources,node_exports,node_publiclookup toneRose
class node_db,node_mail,node_drive,node_datamodel toneIndigo
```

## Components

### Web portal

- [Route shell](https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth state](https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Entry workspace](https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/contestant/Submissions.tsx): `frontend/src/pages/contestant/Submissions.tsx`
- [Judge workspace](https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/judge/Submissions.tsx): `frontend/src/pages/judge/Submissions.tsx`
- [Admin workspaces](https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/tw_admin/Submissions.tsx): `frontend/src/pages/tw_admin/Submissions.tsx`
- [Public lookup](https://github.com/ngtruongmetin/twd_hpd/blob/main/frontend/src/pages/LookupSubmissions.tsx): `frontend/src/pages/LookupSubmissions.tsx`

### API and access

- [HTTP server](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/server.js): `backend/server.js`
- [Session authorization](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/middlewares/AuthMiddleware.js): `backend/middlewares/AuthMiddleware.js`
- [Account access](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/AuthController.js): `backend/controllers/AuthController.js`

### Competition workflow

- [Submission handling](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/SubmissionController.js): `backend/controllers/SubmissionController.js`
- [Judge scoring](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/JudgeScoreController.js): `backend/controllers/JudgeScoreController.js`
- [Result finalization](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/SubmissionResultController.js): `backend/controllers/SubmissionResultController.js`
- [Score totals](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/services/ScoreTotalService.js): `backend/services/ScoreTotalService.js`
- [Complaint messaging](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/ComplaintController.js): `backend/controllers/ComplaintController.js`
- [Voting metrics](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/services/VoteMetricsService.js): `backend/services/VoteMetricsService.js`

### Administration and reporting

- [Central administration](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/TwAdminController.js): `backend/controllers/TwAdminController.js`
- [Technical administration](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/TechAdminController.js): `backend/controllers/TechAdminController.js`
- [Resource management](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/ResourceController.js): `backend/controllers/ResourceController.js`
- [Exports and statistics](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/ExportController.js): `backend/controllers/ExportController.js`
- [Public lookup API](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/controllers/PublicLookupController.js): `backend/controllers/PublicLookupController.js`

### Storage and integrations

- [SQLite database](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/utils/db.js): `backend/utils/db.js`
- [Mail delivery](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/utils/mailer.js): `backend/utils/mailer.js`
- [Google Drive](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/utils/google.js): `backend/utils/google.js`
- [Export formatting](https://github.com/ngtruongmetin/twd_hpd/blob/main/backend/models/DataModel.js): `backend/models/DataModel.js`

### Other components

- **Portal users**

## Connections

- Portal users → Route shell: uses portal (evidence: `frontend/src/App.tsx`)
- Route shell → Auth state: provides auth (evidence: `frontend/src/App.tsx`)
- Route shell → Entry workspace: routes contestants (evidence: `frontend/src/App.tsx`)
- Route shell → Judge workspace: routes judges (evidence: `frontend/src/App.tsx`)
- Route shell → Admin workspaces: routes admins (evidence: `frontend/src/App.tsx`)
- Route shell → Public lookup: routes lookup (evidence: `frontend/src/App.tsx`)
- Entry workspace → HTTP server: requests API
- Judge workspace → HTTP server: requests API
- Admin workspaces → HTTP server: requests API
- Public lookup → HTTP server: requests API
- HTTP server → Session authorization: protects routes (evidence: `backend/server.js`)
- HTTP server → Submission handling: routes submissions
- HTTP server → Judge scoring: routes scores
- HTTP server → Central administration: routes admin
- HTTP server → SQLite database: initializes schema (evidence: `backend/server.js`)
- Submission handling → SQLite database: reads and writes (evidence: `backend/controllers/SubmissionController.js`)
- Judge scoring → Score totals: calculates totals (evidence: `backend/controllers/JudgeScoreController.js`)
- Judge scoring → SQLite database: reads and writes (evidence: `backend/controllers/JudgeScoreController.js`)
- Result finalization → Score totals: calculates totals (evidence: `backend/controllers/SubmissionResultController.js`)
- Result finalization → SQLite database: reads and writes (evidence: `backend/controllers/SubmissionResultController.js`)
- Central administration → Voting metrics: uses metrics (evidence: `backend/controllers/TwAdminController.js`)
- Central administration → SQLite database: reads and writes (evidence: `backend/controllers/TwAdminController.js`)
- Exports and statistics → SQLite database: queries data (evidence: `backend/controllers/ExportController.js`)
- Exports and statistics → Export formatting: formats export (evidence: `backend/controllers/ExportController.js`)
- Exports and statistics → SQLite database: loads provinces (evidence: `backend/controllers/ExportController.js`)
- Resource management → SQLite database: manages records (evidence: `backend/controllers/ResourceController.js`)
- Public lookup API → SQLite database: queries entries (evidence: `backend/controllers/PublicLookupController.js`)
- Account access → SQLite database: reads and writes (evidence: `backend/controllers/AuthController.js`)
- Account access → Mail delivery: sends messages (evidence: `backend/controllers/AuthController.js`)
- Submission handling → Google Drive: checks Drive links
- Complaint messaging → SQLite database: stores messages
