# echynnz/ecinamprem architecture

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

- Interactive diagram: https://gitdiagram.com/echynnz/ecinamprem
- Repository: https://github.com/echynnz/ecinamprem

## Overview

This is a web service for sending email magic links and using them to sign in and attempt premium activation. The main workflow is served through the API router: request a link, submit the link and owner message, authenticate, check prior registration, attempt activation, then record and report the outcome. Separate endpoints expose health, status, history and statistics. Turso-backed registration and activation data support these flows; an optional Telegram bot sends notifications and provides server-status and history commands. Source excerpts establish the main calls; unsampled route and storage behavior is included only where the SOURCE INDEX identifies it.

Main entry points: [`app/api/verify-link/route.js`](https://github.com/echynnz/ecinamprem/blob/main/app/api/verify-link/route.js) (Verify endpoint), [`app/api/route.js`](https://github.com/echynnz/ecinamprem/blob/main/app/api/route.js) (API router), [`lib/history.js`](https://github.com/echynnz/ecinamprem/blob/main/lib/history.js) (Activation history), [`lib/auth.js`](https://github.com/echynnz/ecinamprem/blob/main/lib/auth.js) (Auth and activation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Web runtime"]
  node_server["Express server<br/>[server.js]"]
  node_web["Web client<br/>[index.html]"]
end

subgraph group_api["API endpoints"]
  node_api_router["API router<br/>[route.js]"]
  node_status["Status endpoint<br/>[route.js]"]
  node_send_link["Send-link endpoint<br/>[route.js]"]
  node_verify["Verify endpoint<br/>[route.js]"]
  node_health["Health endpoint<br/>[route.js]"]
  node_history_api["History endpoint<br/>[route.js]"]
  node_stats_api["Stats endpoint<br/>[route.js]"]
end

subgraph group_activation["Activation services"]
  node_auth["Auth and activation<br/>[auth.js]"]
  node_error_map["Auth error mapping<br/>[errors.js]"]
  node_audit["Audit logging<br/>[audit.js]"]
end

subgraph group_data["Persistence"]
  node_registrations["Registration records<br/>[registrations.js]"]
  node_history["Activation history<br/>[history.js]"]
  node_stats["Activation statistics<br/>[stats.js]"]
  node_db[("Turso database<br/>[db.js]")]
end

subgraph group_telegram["Telegram operations"]
  node_telegram["Telegram bot<br/>[telegram.js]"]
end

node_user(("Web user"))
node_identity["Firebase Identity Toolkit"]
node_purchase["Purchase verification service"]
node_turso[("Turso")]
node_telegram_service["Telegram service"]

node_server -->|"serves static files"| node_web
node_server -->|"mounts API"| node_api_router
node_server -->|"starts bot"| node_telegram
node_api_router -->|"routes requests"| node_status
node_api_router -->|"routes requests"| node_send_link
node_api_router -->|"routes requests"| node_verify
node_api_router -->|"routes requests"| node_health
node_api_router -->|"routes requests"| node_history_api
node_api_router -->|"routes requests"| node_stats_api
node_send_link -->|"requests magic link"| node_auth
node_send_link -->|"maps errors"| node_error_map
node_verify -->|"authenticates and activates"| node_auth
node_verify -->|"maps errors"| node_error_map
node_verify -->|"checks and records"| node_registrations
node_verify -->|"records activation"| node_history
node_verify -->|"gets statistics"| node_stats
node_verify -->|"writes audit events"| node_audit
node_verify -->|"sends notifications"| node_telegram
node_history_api -->|"reads history"| node_history
node_stats_api -->|"gets statistics"| node_stats
node_health -->|"checks database"| node_db
node_auth -->|"calls identity APIs"| node_identity
node_auth -->|"requests verification"| node_purchase
node_registrations -->|"reads and writes"| node_db
node_history -->|"reads and writes"| node_db
node_stats -->|"gets counts"| node_history
node_db -->|"queries database"| node_turso
node_telegram -->|"reads history"| node_history
node_telegram -->|"sends messages and polls"| node_telegram_service
node_user -.->|"uses client"| node_web

click node_server "https://github.com/echynnz/ecinamprem/blob/main/server.js"
click node_web "https://github.com/echynnz/ecinamprem/blob/main/public/index.html"
click node_api_router "https://github.com/echynnz/ecinamprem/blob/main/app/api/route.js"
click node_status "https://github.com/echynnz/ecinamprem/blob/main/app/api/status/route.js"
click node_send_link "https://github.com/echynnz/ecinamprem/blob/main/app/api/send-link/route.js"
click node_verify "https://github.com/echynnz/ecinamprem/blob/main/app/api/verify-link/route.js"
click node_health "https://github.com/echynnz/ecinamprem/blob/main/app/api/health/route.js"
click node_history_api "https://github.com/echynnz/ecinamprem/blob/main/app/api/history/route.js"
click node_stats_api "https://github.com/echynnz/ecinamprem/blob/main/app/api/stats/route.js"
click node_auth "https://github.com/echynnz/ecinamprem/blob/main/lib/auth.js"
click node_error_map "https://github.com/echynnz/ecinamprem/blob/main/lib/errors.js"
click node_registrations "https://github.com/echynnz/ecinamprem/blob/main/lib/registrations.js"
click node_history "https://github.com/echynnz/ecinamprem/blob/main/lib/history.js"
click node_stats "https://github.com/echynnz/ecinamprem/blob/main/lib/stats.js"
click node_audit "https://github.com/echynnz/ecinamprem/blob/main/lib/audit.js"
click node_db "https://github.com/echynnz/ecinamprem/blob/main/lib/db.js"
click node_telegram "https://github.com/echynnz/ecinamprem/blob/main/lib/telegram.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_server,node_web,node_user toneBlue
class node_api_router,node_status,node_send_link,node_verify,node_health,node_history_api,node_stats_api,node_turso toneAmber
class node_auth,node_error_map,node_audit toneMint
class node_registrations,node_history,node_stats,node_db toneRose
class node_telegram,node_identity,node_purchase,node_telegram_service toneIndigo
```

## Components

### Web runtime

- [Express server](https://github.com/echynnz/ecinamprem/blob/main/server.js): `server.js`
- [Web client](https://github.com/echynnz/ecinamprem/blob/main/public/index.html): `public/index.html`

### API endpoints

- [API router](https://github.com/echynnz/ecinamprem/blob/main/app/api/route.js): `app/api/route.js`
- [Status endpoint](https://github.com/echynnz/ecinamprem/blob/main/app/api/status/route.js): `app/api/status/route.js`
- [Send-link endpoint](https://github.com/echynnz/ecinamprem/blob/main/app/api/send-link/route.js): `app/api/send-link/route.js`
- [Verify endpoint](https://github.com/echynnz/ecinamprem/blob/main/app/api/verify-link/route.js): `app/api/verify-link/route.js`
- [Health endpoint](https://github.com/echynnz/ecinamprem/blob/main/app/api/health/route.js): `app/api/health/route.js`
- [History endpoint](https://github.com/echynnz/ecinamprem/blob/main/app/api/history/route.js): `app/api/history/route.js`
- [Stats endpoint](https://github.com/echynnz/ecinamprem/blob/main/app/api/stats/route.js): `app/api/stats/route.js`

### Activation services

- [Auth and activation](https://github.com/echynnz/ecinamprem/blob/main/lib/auth.js): `lib/auth.js`
- [Auth error mapping](https://github.com/echynnz/ecinamprem/blob/main/lib/errors.js): `lib/errors.js`
- [Audit logging](https://github.com/echynnz/ecinamprem/blob/main/lib/audit.js): `lib/audit.js`

### Persistence

- [Registration records](https://github.com/echynnz/ecinamprem/blob/main/lib/registrations.js): `lib/registrations.js`
- [Activation history](https://github.com/echynnz/ecinamprem/blob/main/lib/history.js): `lib/history.js`
- [Activation statistics](https://github.com/echynnz/ecinamprem/blob/main/lib/stats.js): `lib/stats.js`
- [Turso database](https://github.com/echynnz/ecinamprem/blob/main/lib/db.js): `lib/db.js`

### Telegram operations

- [Telegram bot](https://github.com/echynnz/ecinamprem/blob/main/lib/telegram.js): `lib/telegram.js`

### Other components

- **Web user**
- **Firebase Identity Toolkit**
- **Purchase verification service**
- **Turso**
- **Telegram service**

## Connections

- Express server → Web client: serves static files (evidence: `server.js`)
- Express server → API router: mounts API (evidence: `server.js`)
- Express server → Telegram bot: starts bot (evidence: `server.js`)
- API router → Status endpoint: routes requests (evidence: `app/api/route.js`)
- API router → Send-link endpoint: routes requests (evidence: `app/api/route.js`)
- API router → Verify endpoint: routes requests (evidence: `app/api/route.js`)
- API router → Health endpoint: routes requests (evidence: `app/api/route.js`)
- API router → History endpoint: routes requests (evidence: `app/api/route.js`)
- API router → Stats endpoint: routes requests (evidence: `app/api/route.js`)
- Send-link endpoint → Auth and activation: requests magic link (evidence: `app/api/send-link/route.js`)
- Send-link endpoint → Auth error mapping: maps errors (evidence: `app/api/send-link/route.js`)
- Verify endpoint → Auth and activation: authenticates and activates (evidence: `app/api/verify-link/route.js`)
- Verify endpoint → Auth error mapping: maps errors (evidence: `app/api/verify-link/route.js`)
- Verify endpoint → Registration records: checks and records (evidence: `app/api/verify-link/route.js`)
- Verify endpoint → Activation history: records activation (evidence: `app/api/verify-link/route.js`)
- Verify endpoint → Activation statistics: gets statistics (evidence: `app/api/verify-link/route.js`)
- Verify endpoint → Audit logging: writes audit events (evidence: `app/api/verify-link/route.js`)
- Verify endpoint → Telegram bot: sends notifications (evidence: `app/api/verify-link/route.js`)
- History endpoint → Activation history: reads history (evidence: `app/api/history/route.js`)
- Stats endpoint → Activation statistics: gets statistics (evidence: `app/api/stats/route.js`)
- Health endpoint → Turso database: checks database (evidence: `app/api/health/route.js`)
- Auth and activation → Firebase Identity Toolkit: calls identity APIs (evidence: `lib/auth.js`)
- Auth and activation → Purchase verification service: requests verification (evidence: `lib/auth.js`)
- Registration records → Turso database: reads and writes (evidence: `lib/registrations.js`)
- Activation history → Turso database: reads and writes (evidence: `lib/history.js`)
- Activation statistics → Activation history: gets counts (evidence: `lib/stats.js`)
- Turso database → Turso: queries database (evidence: `lib/db.js`)
- Telegram bot → Activation history: reads history (evidence: `lib/telegram.js`)
- Telegram bot → Telegram service: sends messages and polls (evidence: `lib/telegram.js`)
- Web user → Web client: uses client
