# hmddevs/hmd-bio architecture

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

- Interactive diagram: https://gitdiagram.com/hmddevs/hmd-bio
- Repository: https://github.com/hmddevs/hmd-bio

## Overview

HMD.bio is a URL-shortening and link-analytics platform. Visitors submit destinations for short links, then follow a short URL through the edge proxy to resolution and click recording. Registered users manage links, review analytics, and attach verified custom domains; the REST API and admin dashboard expose additional management capabilities. The graph includes the documented dashboard, bookmarklet, previews, QR codes, bulk/export, and admin capabilities. Some UI-to-handler wiring is not shown in the sampled source, so those links are omitted.

Main entry points: [`src/app/api/v1/domains`](https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/domains) (Domain Management API), [`src/app/api/internal/resolve/route.ts`](https://github.com/hmddevs/hmd-bio/blob/main/src/app/api/internal/resolve/route.ts) (Link Resolver), [`src/models/Link.ts`](https://github.com/hmddevs/hmd-bio/blob/main/src/models/Link.ts) (Link Records), [`src/models/Click.ts`](https://github.com/hmddevs/hmd-bio/blob/main/src/models/Click.ts) (Click Records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_public_ui["Public Pages<br/>[page.tsx]"]
  node_dashboard_ui["User Dashboard"]
  node_preview_stats["Preview and Stats<br/>[page.tsx]"]
  node_bookmarklet["Bookmarklet<br/>[page.tsx]"]
end

subgraph group_links["Link Lifecycle"]
  node_shorten_api["Shorten Endpoint<br/>[route.ts]"]
  node_links_api["Link Management API"]
  node_redirect_proxy["Edge Redirect<br/>[proxy.ts]"]
  node_resolve_route["Link Resolver<br/>[route.ts]"]
  node_link_model[("Link Records<br/>[Link.ts]")]
  node_link_cache["Redirect Cache<br/>[link-cache.ts]"]
end

subgraph group_identity["Identity and API"]
  node_auth_routes["Signup and Login"]
  node_auth_services["Authentication Services<br/>[auth.ts]"]
end

subgraph group_domains["Custom Domains"]
  node_domain_api["Domain Management API"]
  node_domain_services["Domain Services<br/>[domains.ts]"]
  node_domain_config["Domain Config Route<br/>[route.ts]"]
  node_vercel_domains["Vercel Domains"]
end

subgraph group_analytics["Analytics and Admin"]
  node_click_model[("Click Records<br/>[Click.ts]")]
  node_stats_api["Analytics API"]
  node_admin_ui["Admin Dashboard"]
  node_admin_api["Admin API"]
end

node_visitor(("Visitor"))
node_account_user(("Account User"))
node_api_caller(("API Caller"))
node_mongo[("MongoDB")]
node_dns["DNS"]

node_visitor -->|"opens pages"| node_public_ui
node_visitor -->|"follows short URL"| node_redirect_proxy
node_account_user -->|"manages links"| node_dashboard_ui
node_account_user -->|"registers or signs in"| node_auth_routes
node_api_caller -->|"submits URL"| node_shorten_api
node_api_caller -->|"manages links"| node_links_api
node_shorten_api -->|"creates link"| node_link_model
node_shorten_api -->|"invalidates entry"| node_link_cache
node_links_api -->|"reads and updates"| node_link_model
node_links_api -->|"invalidates entries"| node_link_cache
node_redirect_proxy -->|"requests resolution"| node_resolve_route
node_redirect_proxy -->|"requests domain config"| node_domain_config
node_resolve_route -->|"looks up link"| node_link_model
node_resolve_route -->|"records click"| node_click_model
node_resolve_route -->|"refreshes entry"| node_link_cache
node_auth_routes -->|"authenticates"| node_auth_services
node_domain_api -->|"uses domain logic"| node_domain_services
node_domain_api -->|"reads and writes domains"| node_mongo
node_domain_api -.->|"attaches or removes"| node_vercel_domains
node_domain_api -->|"provides verification records"| node_dns
node_domain_config -->|"loads config"| node_domain_services
node_domain_config -->|"reads domain config"| node_mongo
node_preview_stats -->|"displays analytics"| node_stats_api
node_stats_api -->|"reads click data"| node_click_model
node_dashboard_ui --> node_admin_ui
node_admin_ui -->|"manages users and domains"| node_admin_api
node_admin_api -->|"reads click records"| node_click_model
node_admin_api -->|"queries records"| node_mongo
node_link_model -->|"persists links"| node_mongo
node_click_model -->|"persists clicks"| node_mongo

click node_public_ui "https://github.com/hmddevs/hmd-bio/blob/main/src/app/page.tsx"
click node_dashboard_ui "https://github.com/hmddevs/hmd-bio/tree/main/src/app/dashboard"
click node_preview_stats "https://github.com/hmddevs/hmd-bio/blob/main/src/app/preview/%5Bkeyword%5D/page.tsx"
click node_bookmarklet "https://github.com/hmddevs/hmd-bio/blob/main/src/app/bookmarklet/page.tsx"
click node_shorten_api "https://github.com/hmddevs/hmd-bio/blob/main/src/app/api/v1/shorten/route.ts"
click node_links_api "https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/links"
click node_redirect_proxy "https://github.com/hmddevs/hmd-bio/blob/main/src/proxy.ts"
click node_resolve_route "https://github.com/hmddevs/hmd-bio/blob/main/src/app/api/internal/resolve/route.ts"
click node_link_model "https://github.com/hmddevs/hmd-bio/blob/main/src/models/Link.ts"
click node_link_cache "https://github.com/hmddevs/hmd-bio/blob/main/src/lib/link-cache.ts"
click node_auth_routes "https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/auth"
click node_auth_services "https://github.com/hmddevs/hmd-bio/blob/main/src/lib/auth.ts"
click node_domain_api "https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/domains"
click node_domain_services "https://github.com/hmddevs/hmd-bio/blob/main/src/lib/domains.ts"
click node_domain_config "https://github.com/hmddevs/hmd-bio/blob/main/src/app/api/internal/domain-config/route.ts"
click node_click_model "https://github.com/hmddevs/hmd-bio/blob/main/src/models/Click.ts"
click node_stats_api "https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/stats"
click node_admin_ui "https://github.com/hmddevs/hmd-bio/tree/main/src/app/admin/(dashboard)"
click node_admin_api "https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/admin"

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_public_ui,node_dashboard_ui,node_preview_stats,node_bookmarklet,node_account_user toneBlue
class node_shorten_api,node_links_api,node_redirect_proxy,node_resolve_route,node_link_model,node_link_cache,node_mongo toneAmber
class node_auth_routes,node_auth_services,node_api_caller toneMint
class node_domain_api,node_domain_services,node_domain_config,node_vercel_domains toneRose
class node_click_model,node_stats_api,node_admin_ui,node_admin_api,node_visitor,node_dns toneIndigo
```

## Components

### User Experience

- [Public Pages](https://github.com/hmddevs/hmd-bio/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [User Dashboard](https://github.com/hmddevs/hmd-bio/tree/main/src/app/dashboard): `src/app/dashboard`
- [Preview and Stats](https://github.com/hmddevs/hmd-bio/blob/main/src/app/preview/%5Bkeyword%5D/page.tsx): `src/app/preview/[keyword]/page.tsx`
- [Bookmarklet](https://github.com/hmddevs/hmd-bio/blob/main/src/app/bookmarklet/page.tsx): `src/app/bookmarklet/page.tsx`

### Link Lifecycle

- [Shorten Endpoint](https://github.com/hmddevs/hmd-bio/blob/main/src/app/api/v1/shorten/route.ts): `src/app/api/v1/shorten/route.ts`
- [Link Management API](https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/links): `src/app/api/v1/links`
- [Edge Redirect](https://github.com/hmddevs/hmd-bio/blob/main/src/proxy.ts): `src/proxy.ts`
- [Link Resolver](https://github.com/hmddevs/hmd-bio/blob/main/src/app/api/internal/resolve/route.ts): `src/app/api/internal/resolve/route.ts`
- [Link Records](https://github.com/hmddevs/hmd-bio/blob/main/src/models/Link.ts): `src/models/Link.ts`
- [Redirect Cache](https://github.com/hmddevs/hmd-bio/blob/main/src/lib/link-cache.ts): `src/lib/link-cache.ts`

### Identity and API

- [Signup and Login](https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/auth): `src/app/api/v1/auth`
- [Authentication Services](https://github.com/hmddevs/hmd-bio/blob/main/src/lib/auth.ts): `src/lib/auth.ts`

### Custom Domains

- [Domain Management API](https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/domains): `src/app/api/v1/domains`
- [Domain Services](https://github.com/hmddevs/hmd-bio/blob/main/src/lib/domains.ts): `src/lib/domains.ts`
- [Domain Config Route](https://github.com/hmddevs/hmd-bio/blob/main/src/app/api/internal/domain-config/route.ts): `src/app/api/internal/domain-config/route.ts`
- **Vercel Domains**

### Analytics and Admin

- [Click Records](https://github.com/hmddevs/hmd-bio/blob/main/src/models/Click.ts): `src/models/Click.ts`
- [Analytics API](https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/stats): `src/app/api/v1/stats`
- [Admin Dashboard](https://github.com/hmddevs/hmd-bio/tree/main/src/app/admin/(dashboard)): `src/app/admin/(dashboard)`
- [Admin API](https://github.com/hmddevs/hmd-bio/tree/main/src/app/api/v1/admin): `src/app/api/v1/admin`

### Other components

- **Visitor**
- **Account User**
- **API Caller**
- **MongoDB**
- **DNS**

## Connections

- Visitor → Public Pages: opens pages
- Visitor → Edge Redirect: follows short URL
- Account User → User Dashboard: manages links
- Account User → Signup and Login: registers or signs in
- API Caller → Shorten Endpoint: submits URL
- API Caller → Link Management API: manages links
- Shorten Endpoint → Link Records: creates link
- Shorten Endpoint → Redirect Cache: invalidates entry
- Link Management API → Link Records: reads and updates
- Link Management API → Redirect Cache: invalidates entries
- Edge Redirect → Link Resolver: requests resolution
- Edge Redirect → Domain Config Route: requests domain config
- Link Resolver → Link Records: looks up link
- Link Resolver → Click Records: records click
- Link Resolver → Redirect Cache: refreshes entry
- Signup and Login → Authentication Services: authenticates
- Domain Management API → Domain Services: uses domain logic
- Domain Management API → MongoDB: reads and writes domains
- Domain Management API → Vercel Domains: attaches or removes
- Domain Management API → DNS: provides verification records
- Domain Config Route → Domain Services: loads config
- Domain Config Route → MongoDB: reads domain config
- Preview and Stats → Analytics API: displays analytics
- Analytics API → Click Records: reads click data
- User Dashboard → Admin Dashboard
- Admin Dashboard → Admin API: manages users and domains
- Admin API → Click Records: reads click records
- Admin API → MongoDB: queries records
- Link Records → MongoDB: persists links
- Click Records → MongoDB: persists clicks