# rk936503/url-shortener-api architecture

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

- Interactive diagram: https://gitdiagram.com/rk936503/url-shortener-api
- Repository: https://github.com/rk936503/url-shortener-api

## Overview

This is an Express URL-shortener API: users register or log in to obtain a JWT, then create, list, delete, and resolve short links. The API also exposes health, version, and Prometheus metrics endpoints. The graph follows the sampled request handlers and middleware; monitoring connections and dashboard capabilities are included where the README documents them, while deployment and CI infrastructure are omitted.

Main entry points: [`index.js`](https://github.com/rk936503/url-shortener-api/blob/main/index.js) (Express app), [`routes/user.routes.js`](https://github.com/rk936503/url-shortener-api/blob/main/routes/user.routes.js) (User routes), [`db/index.js`](https://github.com/rk936503/url-shortener-api/blob/main/db/index.js) (Drizzle client), [`routes/url.routes.js`](https://github.com/rk936503/url-shortener-api/blob/main/routes/url.routes.js) (URL routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_app["Express app<br/>[index.js]"]
  node_user_routes["User routes<br/>[user.routes.js]"]
  node_url_routes["URL routes<br/>[url.routes.js]"]
  node_request_validation["Request schemas"]
end

subgraph group_identity["Identity"]
  node_auth_middleware["Auth middleware<br/>[auth.middleware.js]"]
  node_user_service["User lookup<br/>[user.service.js]"]
  node_password_hash["Password hashing<br/>[hash.js]"]
  node_token["JWT tokens<br/>[token.js]"]
  node_token_validation["Token schema"]
end

subgraph group_data["Persistence"]
  node_db_client["Drizzle client<br/>[index.js]"]
  node_users_model["User schema<br/>[user.model.js]"]
  node_urls_model["URL schema<br/>[url.model.js]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_observability["Observability"]
  node_logging["Request logging"]
  node_metrics_middleware["HTTP metrics"]
  node_metrics_registry["Metrics registry<br/>[metrics.js]"]
  node_prometheus["Prometheus<br/>[prometheus.yml]"]
  node_grafana["Grafana dashboards<br/>[url-shortener.json]"]
  node_prom_datasource["Prometheus datasource<br/>[prometheus.yml]"]
end

node_user(("API user"))

node_user -->|"sends requests"| node_app
node_app -->|"mounts /user"| node_user_routes
node_app -->|"mounts routes"| node_url_routes
node_app -->|"runs authentication"| node_auth_middleware
node_app -->|"runs metrics"| node_metrics_middleware
node_app -->|"runs logging"| node_logging
node_user_routes -->|"validates input"| node_request_validation
node_url_routes -->|"validates input"| node_request_validation
node_user_routes -->|"looks up user"| node_user_service
node_user_routes -->|"hashes password"| node_password_hash
node_user_routes -->|"creates token"| node_token
node_user_routes -->|"writes user"| node_db_client
node_url_routes -->|"reads and writes URLs"| node_db_client
node_url_routes -->|"guards operations"| node_auth_middleware
node_auth_middleware -->|"validates token"| node_token
node_user_service -->|"queries users"| node_db_client
node_token -->|"validates claims"| node_token_validation
node_db_client -->|"uses schema"| node_users_model
node_db_client -->|"uses schema"| node_urls_model
node_db_client -->|"queries"| node_postgres
node_metrics_middleware -->|"records metrics"| node_metrics_registry
node_app -->|"serves /metrics"| node_metrics_registry
node_prometheus -->|"scrapes metrics"| node_app
node_grafana -->|"uses datasource"| node_prom_datasource
node_prom_datasource -->|"queries metrics"| node_prometheus

click node_app "https://github.com/rk936503/url-shortener-api/blob/main/index.js"
click node_user_routes "https://github.com/rk936503/url-shortener-api/blob/main/routes/user.routes.js"
click node_url_routes "https://github.com/rk936503/url-shortener-api/blob/main/routes/url.routes.js"
click node_request_validation "https://github.com/rk936503/url-shortener-api/blob/main/validation/request.validation.js"
click node_auth_middleware "https://github.com/rk936503/url-shortener-api/blob/main/middlewares/auth.middleware.js"
click node_user_service "https://github.com/rk936503/url-shortener-api/blob/main/services/user.service.js"
click node_password_hash "https://github.com/rk936503/url-shortener-api/blob/main/utils/hash.js"
click node_token "https://github.com/rk936503/url-shortener-api/blob/main/utils/token.js"
click node_token_validation "https://github.com/rk936503/url-shortener-api/blob/main/validation/token.validation.js"
click node_db_client "https://github.com/rk936503/url-shortener-api/blob/main/db/index.js"
click node_users_model "https://github.com/rk936503/url-shortener-api/blob/main/models/user.model.js"
click node_urls_model "https://github.com/rk936503/url-shortener-api/blob/main/models/url.model.js"
click node_logging "https://github.com/rk936503/url-shortener-api/blob/main/middlewares/logging.middleware.js"
click node_metrics_middleware "https://github.com/rk936503/url-shortener-api/blob/main/middlewares/metrics.middleware.js"
click node_metrics_registry "https://github.com/rk936503/url-shortener-api/blob/main/utils/metrics.js"
click node_prometheus "https://github.com/rk936503/url-shortener-api/blob/main/prometheus.yml"
click node_grafana "https://github.com/rk936503/url-shortener-api/blob/main/grafana/provisioning/dashboards/json/url-shortener.json"
click node_prom_datasource "https://github.com/rk936503/url-shortener-api/blob/main/grafana/provisioning/datasources/prometheus.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_app,node_user_routes,node_url_routes,node_request_validation,node_user toneBlue
class node_auth_middleware,node_user_service,node_password_hash,node_token,node_token_validation toneAmber
class node_db_client,node_users_model,node_urls_model,node_postgres toneMint
class node_logging,node_metrics_middleware,node_metrics_registry,node_prometheus,node_grafana,node_prom_datasource toneRose
```

## Components

### REST API

- [Express app](https://github.com/rk936503/url-shortener-api/blob/main/index.js): `index.js`
- [User routes](https://github.com/rk936503/url-shortener-api/blob/main/routes/user.routes.js): `routes/user.routes.js`
- [URL routes](https://github.com/rk936503/url-shortener-api/blob/main/routes/url.routes.js): `routes/url.routes.js`
- [Request schemas](https://github.com/rk936503/url-shortener-api/blob/main/validation/request.validation.js): `validation/request.validation.js`

### Identity

- [Auth middleware](https://github.com/rk936503/url-shortener-api/blob/main/middlewares/auth.middleware.js): `middlewares/auth.middleware.js`
- [User lookup](https://github.com/rk936503/url-shortener-api/blob/main/services/user.service.js): `services/user.service.js`
- [Password hashing](https://github.com/rk936503/url-shortener-api/blob/main/utils/hash.js): `utils/hash.js`
- [JWT tokens](https://github.com/rk936503/url-shortener-api/blob/main/utils/token.js): `utils/token.js`
- [Token schema](https://github.com/rk936503/url-shortener-api/blob/main/validation/token.validation.js): `validation/token.validation.js`

### Persistence

- [Drizzle client](https://github.com/rk936503/url-shortener-api/blob/main/db/index.js): `db/index.js`
- [User schema](https://github.com/rk936503/url-shortener-api/blob/main/models/user.model.js): `models/user.model.js`
- [URL schema](https://github.com/rk936503/url-shortener-api/blob/main/models/url.model.js): `models/url.model.js`
- **PostgreSQL**

### Observability

- [Request logging](https://github.com/rk936503/url-shortener-api/blob/main/middlewares/logging.middleware.js): `middlewares/logging.middleware.js`
- [HTTP metrics](https://github.com/rk936503/url-shortener-api/blob/main/middlewares/metrics.middleware.js): `middlewares/metrics.middleware.js`
- [Metrics registry](https://github.com/rk936503/url-shortener-api/blob/main/utils/metrics.js): `utils/metrics.js`
- [Prometheus](https://github.com/rk936503/url-shortener-api/blob/main/prometheus.yml): `prometheus.yml`
- [Grafana dashboards](https://github.com/rk936503/url-shortener-api/blob/main/grafana/provisioning/dashboards/json/url-shortener.json): `grafana/provisioning/dashboards/json/url-shortener.json`
- [Prometheus datasource](https://github.com/rk936503/url-shortener-api/blob/main/grafana/provisioning/datasources/prometheus.yml): `grafana/provisioning/datasources/prometheus.yml`

### Other components

- **API user**

## Connections

- API user → Express app: sends requests
- Express app → User routes: mounts /user
- Express app → URL routes: mounts routes
- Express app → Auth middleware: runs authentication
- Express app → HTTP metrics: runs metrics
- Express app → Request logging: runs logging
- User routes → Request schemas: validates input
- URL routes → Request schemas: validates input
- User routes → User lookup: looks up user
- User routes → Password hashing: hashes password
- User routes → JWT tokens: creates token
- User routes → Drizzle client: writes user
- URL routes → Drizzle client: reads and writes URLs
- URL routes → Auth middleware: guards operations
- Auth middleware → JWT tokens: validates token
- User lookup → Drizzle client: queries users
- JWT tokens → Token schema: validates claims
- Drizzle client → User schema: uses schema
- Drizzle client → URL schema: uses schema
- Drizzle client → PostgreSQL: queries
- HTTP metrics → Metrics registry: records metrics
- Express app → Metrics registry: serves /metrics
- Prometheus → Express app: scrapes metrics
- Grafana dashboards → Prometheus datasource: uses datasource
- Prometheus datasource → Prometheus: queries metrics