# metakgp/naarad architecture

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

- Interactive diagram: https://gitdiagram.com/metakgp/naarad
- Repository: https://github.com/metakgp/naarad

## Overview

Naarad is a self-hosted ntfy service for KGP notices, with a custom institute-user signup flow. The signup page requests registration; the backend validates Heimdall identity, creates an ntfy account, grants channel access, and emails credentials. The README also documents the ntfy service’s caching, attachments, web interface, push notifications, logging, and rate limiting. Relationships for the signup flow are supported by excerpts; broader ntfy capabilities and Heimdall protection are documented in the README, while the ntfy server internals are not present in this tree.

Main entry points: [`backend/main.go`](https://github.com/metakgp/naarad/blob/main/backend/main.go) (Registration API), [`frontend/src/pages/Register.tsx`](https://github.com/metakgp/naarad/blob/main/frontend/src/pages/Register.tsx) (Registration page), [`server.yml`](https://github.com/metakgp/naarad/blob/main/server.yml) (Ntfy notifications), [`frontend/src/index.tsx`](https://github.com/metakgp/naarad/blob/main/frontend/src/index.tsx) (Frontend entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_signup_ui["Signup interface"]
  node_frontend_entry["Frontend entry<br/>[index.tsx]"]
  node_signup_app["Signup app<br/>[App.tsx]"]
  node_registration_page["Registration page<br/>[Register.tsx]"]
  node_redirect_toast["Redirect toast<br/>[RedirectToast.tsx]"]
end

subgraph group_signup_backend["Signup backend"]
  node_backend_api["Registration API<br/>[main.go]"]
  node_mailer["Credential mailer<br/>[mail.go]"]
end

subgraph group_ntfy_service["Ntfy service"]
  node_ntfy["Ntfy notifications<br/>[server.yml]"]
end

node_user(("KGP user"))
node_heimdall["Heimdall identity"]
node_ntfy_auth_store[("Ntfy account store")]
node_gmail["Gmail delivery"]
node_notice_subscriber(("KGP subscribers"))

node_user -->|"opens signup"| node_frontend_entry
node_frontend_entry -->|"renders"| node_signup_app
node_signup_app -->|"renders"| node_registration_page
node_registration_page -->|"requests registration"| node_backend_api
node_registration_page -->|"shows redirect"| node_redirect_toast
node_backend_api -->|"validates identity"| node_heimdall
node_backend_api -->|"checks and grants access"| node_ntfy_auth_store
node_backend_api -->|"creates account"| node_ntfy
node_backend_api -->|"sends credentials"| node_mailer
node_mailer -->|"sends email"| node_gmail
node_notice_subscriber -.->|"receives notices"| node_ntfy
node_heimdall -.->|"protects access"| node_ntfy

click node_frontend_entry "https://github.com/metakgp/naarad/blob/main/frontend/src/index.tsx"
click node_signup_app "https://github.com/metakgp/naarad/blob/main/frontend/src/App.tsx"
click node_registration_page "https://github.com/metakgp/naarad/blob/main/frontend/src/pages/Register.tsx"
click node_redirect_toast "https://github.com/metakgp/naarad/blob/main/frontend/src/components/RedirectToast.tsx"
click node_backend_api "https://github.com/metakgp/naarad/blob/main/backend/main.go"
click node_mailer "https://github.com/metakgp/naarad/blob/main/backend/mail.go"
click node_ntfy "https://github.com/metakgp/naarad/blob/main/server.yml"

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_frontend_entry,node_signup_app,node_registration_page,node_redirect_toast,node_user toneBlue
class node_backend_api,node_mailer,node_ntfy_auth_store toneAmber
class node_ntfy toneMint
class node_heimdall,node_gmail,node_notice_subscriber toneIndigo
```

## Components

### Signup interface

- [Frontend entry](https://github.com/metakgp/naarad/blob/main/frontend/src/index.tsx): `frontend/src/index.tsx`
- [Signup app](https://github.com/metakgp/naarad/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Registration page](https://github.com/metakgp/naarad/blob/main/frontend/src/pages/Register.tsx): `frontend/src/pages/Register.tsx`
- [Redirect toast](https://github.com/metakgp/naarad/blob/main/frontend/src/components/RedirectToast.tsx): `frontend/src/components/RedirectToast.tsx`

### Signup backend

- [Registration API](https://github.com/metakgp/naarad/blob/main/backend/main.go): `backend/main.go`
- [Credential mailer](https://github.com/metakgp/naarad/blob/main/backend/mail.go): `backend/mail.go`

### Ntfy service

- [Ntfy notifications](https://github.com/metakgp/naarad/blob/main/server.yml): `server.yml`

### Other components

- **KGP user**
- **Heimdall identity**
- **Ntfy account store**
- **Gmail delivery**
- **KGP subscribers**

## Connections

- KGP user → Frontend entry: opens signup (evidence: `README.md`)
- Frontend entry → Signup app: renders (evidence: `frontend/src/index.tsx`)
- Signup app → Registration page: renders (evidence: `frontend/src/App.tsx`)
- Registration page → Registration API: requests registration (evidence: `frontend/src/pages/Register.tsx`)
- Registration page → Redirect toast: shows redirect (evidence: `frontend/src/pages/Register.tsx`)
- Registration API → Heimdall identity: validates identity (evidence: `backend/main.go`)
- Registration API → Ntfy account store: checks and grants access (evidence: `backend/main.go`)
- Registration API → Ntfy notifications: creates account (evidence: `backend/main.go`)
- Registration API → Credential mailer: sends credentials (evidence: `backend/main.go`)
- Credential mailer → Gmail delivery: sends email (evidence: `backend/mail.go`)
- KGP subscribers → Ntfy notifications: receives notices (evidence: `README.md`)
- Heimdall identity → Ntfy notifications: protects access (evidence: `README.md`)
