# rafzzzaza/kidou-am architecture

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

- Interactive diagram: https://gitdiagram.com/rafzzzaza/kidou-am
- Repository: https://github.com/rafzzzaza/kidou-am

## Overview

Kidou AM is a web UI and HTTP API for Alight Motion Premium activation using email magic links. Users can request a link and verify it manually, or use the one-click flow, which creates a temporary mail.tm account, polls for the message, extracts its code, verifies it, and attempts premium activation. Successful activations update JSONBin-backed statistics. The sampled auto route uses mail.tm, while the README describes a different temporary-mail provider; the separate email-generation route calls that documented provider. UI request wiring is based on the README, not sampled frontend source.

Main entry points: [`app/api/route.js`](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/route.js) (API router), [`app/api/auto/route.js`](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/auto/route.js) (Auto activation), [`lib/auth.js`](https://github.com/rafzzzaza/kidou-am/blob/main/lib/auth.js) (Auth and premium), [`app/api/verify-link/route.js`](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/verify-link/route.js) (Verify link)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web and API"]
  node_web["Web interface<br/>[index.html]"]
  node_server["HTTP server<br/>[server.js]"]
  node_api["API router<br/>[route.js]"]
  node_status["Status endpoint<br/>[route.js]"]
end

subgraph group_activation["Activation flows"]
  node_send["Send link<br/>[route.js]"]
  node_verify["Verify link<br/>[route.js]"]
  node_auto["Auto activation<br/>[route.js]"]
  node_emailgen["Email generation<br/>[route.js]"]
  node_auth["Auth and premium<br/>[auth.js]"]
  node_errors["Error mapping<br/>[errors.js]"]
end

subgraph group_integrations["External services"]
  node_firebase["Firebase Identity"]
  node_purchase["Premium verification"]
  node_mailtm["mail.tm"]
  node_tempmail["Temp mail provider"]
end

subgraph group_state["Activation statistics"]
  node_statsroute["Stats endpoint<br/>[route.js]"]
  node_stats["Stats service<br/>[stats.js]"]
  node_jsonbin[("JSONBin")]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"requests"| node_server
node_server -->|"mounts API"| node_api
node_api -->|"dispatches"| node_status
node_api -->|"dispatches"| node_send
node_api -->|"dispatches"| node_verify
node_api -->|"dispatches"| node_auto
node_api -->|"dispatches"| node_emailgen
node_api -->|"dispatches"| node_statsroute
node_send -->|"requests link"| node_auth
node_send -->|"formats errors"| node_errors
node_auth -->|"calls identity API"| node_firebase
node_verify -->|"verifies and activates"| node_auth
node_verify -->|"formats errors"| node_errors
node_verify -->|"reads or increments"| node_stats
node_auto -->|"creates account, polls inbox"| node_mailtm
node_auto -->|"requests link, verifies, activates"| node_auth
node_auto -->|"formats errors"| node_errors
node_auto -->|"reads or increments"| node_stats
node_auth -->|"verifies purchase"| node_purchase
node_emailgen -->|"generates address"| node_tempmail
node_statsroute -->|"reads stats"| node_stats
node_stats -->|"reads and writes"| node_jsonbin

click node_web "https://github.com/rafzzzaza/kidou-am/blob/main/public/index.html"
click node_server "https://github.com/rafzzzaza/kidou-am/blob/main/server.js"
click node_api "https://github.com/rafzzzaza/kidou-am/blob/main/app/api/route.js"
click node_status "https://github.com/rafzzzaza/kidou-am/blob/main/app/api/status/route.js"
click node_send "https://github.com/rafzzzaza/kidou-am/blob/main/app/api/send-link/route.js"
click node_verify "https://github.com/rafzzzaza/kidou-am/blob/main/app/api/verify-link/route.js"
click node_auto "https://github.com/rafzzzaza/kidou-am/blob/main/app/api/auto/route.js"
click node_emailgen "https://github.com/rafzzzaza/kidou-am/blob/main/app/api/email/route.js"
click node_auth "https://github.com/rafzzzaza/kidou-am/blob/main/lib/auth.js"
click node_errors "https://github.com/rafzzzaza/kidou-am/blob/main/lib/errors.js"
click node_statsroute "https://github.com/rafzzzaza/kidou-am/blob/main/app/api/stats/route.js"
click node_stats "https://github.com/rafzzzaza/kidou-am/blob/main/lib/stats.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_web,node_server,node_api,node_status,node_user toneBlue
class node_send,node_verify,node_auto,node_emailgen,node_auth,node_errors toneAmber
class node_firebase,node_purchase,node_mailtm,node_tempmail toneMint
class node_statsroute,node_stats,node_jsonbin toneRose
```

## Components

### Web and API

- [Web interface](https://github.com/rafzzzaza/kidou-am/blob/main/public/index.html): `public/index.html`
- [HTTP server](https://github.com/rafzzzaza/kidou-am/blob/main/server.js): `server.js`
- [API router](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/route.js): `app/api/route.js`
- [Status endpoint](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/status/route.js): `app/api/status/route.js`

### Activation flows

- [Send link](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/send-link/route.js): `app/api/send-link/route.js`
- [Verify link](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/verify-link/route.js): `app/api/verify-link/route.js`
- [Auto activation](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/auto/route.js): `app/api/auto/route.js`
- [Email generation](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/email/route.js): `app/api/email/route.js`
- [Auth and premium](https://github.com/rafzzzaza/kidou-am/blob/main/lib/auth.js): `lib/auth.js`
- [Error mapping](https://github.com/rafzzzaza/kidou-am/blob/main/lib/errors.js): `lib/errors.js`

### External services

- **Firebase Identity**
- **Premium verification**
- **mail.tm**
- **Temp mail provider**

### Activation statistics

- [Stats endpoint](https://github.com/rafzzzaza/kidou-am/blob/main/app/api/stats/route.js): `app/api/stats/route.js`
- [Stats service](https://github.com/rafzzzaza/kidou-am/blob/main/lib/stats.js): `lib/stats.js`
- **JSONBin**

### Other components

- **User**

## Connections

- User → Web interface: uses
- Web interface → HTTP server: requests
- HTTP server → API router: mounts API
- API router → Status endpoint: dispatches
- API router → Send link: dispatches
- API router → Verify link: dispatches
- API router → Auto activation: dispatches
- API router → Email generation: dispatches
- API router → Stats endpoint: dispatches
- Send link → Auth and premium: requests link
- Send link → Error mapping: formats errors
- Auth and premium → Firebase Identity: calls identity API
- Verify link → Auth and premium: verifies and activates
- Verify link → Error mapping: formats errors
- Verify link → Stats service: reads or increments
- Auto activation → mail.tm: creates account, polls inbox
- Auto activation → Auth and premium: requests link, verifies, activates
- Auto activation → Error mapping: formats errors
- Auto activation → Stats service: reads or increments
- Auth and premium → Premium verification: verifies purchase
- Email generation → Temp mail provider: generates address
- Stats endpoint → Stats service: reads stats
- Stats service → JSONBin: reads and writes