# freeyoshino/url-shortener architecture

> Architecture diagram of the GitHub repository freeyoshino/url-shortener, 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/freeyoshino/url-shortener
- Repository: https://github.com/freeyoshino/url-shortener

## Overview

This is a NestJS URL-shortening service. A user submits a long URL to the URL API, which creates or reuses a short-code record; visiting that code resolves the destination and records a click, while the statistics endpoint reports click totals. The API also supports URL lookup, update, and deletion. Prisma provides persistence to PostgreSQL. The README also describes request limiting as planned; its implementation is not evident in the sampled source, so it is shown as an unverified capability.

Main entry points: [`src/urls/urls.controller.ts`](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/urls.controller.ts) (URL API), [`src/prisma/prisma.service.ts`](https://github.com/freeyoshino/url-shortener/blob/main/src/prisma/prisma.service.ts) (Prisma Service), [`src/urls/redirect.controller.ts`](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/redirect.controller.ts) (Redirect Handler), [`src/urls/urls.service.ts`](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/urls.service.ts) (URL Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_url_api["URL API<br/>[urls.controller.ts]"]
  node_redirect["Redirect Handler"]
  node_rate_limit["Request Limiting"]
end

subgraph group_domain["URL Operations"]
  node_url_service["URL Service<br/>[urls.service.ts]"]
  node_create_dto["Create URL Input<br/>[create-url.dto.ts]"]
  node_update_dto["Update URL Input<br/>[update-url.dto.ts]"]
end

subgraph group_analytics["Click Analytics"]
  node_analytics_service["Analytics Service"]
end

subgraph group_persistence["Persistence"]
  node_prisma_module["Prisma Module<br/>[prisma.module.ts]"]
  node_prisma_service["Prisma Service<br/>[prisma.service.ts]"]
  node_postgres[("PostgreSQL<br/>[schema.prisma]")]
end

node_user(("User"))

node_user -->|"submits URL"| node_url_api
node_user -->|"visits short code"| node_redirect
node_url_api -->|"accepts input"| node_create_dto
node_url_api -->|"accepts input"| node_update_dto
node_url_api -->|"delegates URL work"| node_url_service
node_url_api -->|"requests statistics"| node_analytics_service
node_redirect -->|"resolves short code"| node_url_service
node_redirect -->|"records click"| node_analytics_service
node_url_service -->|"reads and writes URLs"| node_prisma_service
node_analytics_service -->|"records and counts clicks"| node_prisma_service
node_prisma_module -->|"provides"| node_prisma_service
node_prisma_service -->|"connects to"| node_postgres
node_user -.->|"may be throttled"| node_rate_limit

click node_url_api "https://github.com/freeyoshino/url-shortener/blob/main/src/urls/urls.controller.ts"
click node_redirect "https://github.com/freeyoshino/url-shortener/blob/main/src/urls/redirect.controller.ts"
click node_url_service "https://github.com/freeyoshino/url-shortener/blob/main/src/urls/urls.service.ts"
click node_create_dto "https://github.com/freeyoshino/url-shortener/blob/main/src/urls/dto/create-url.dto.ts"
click node_update_dto "https://github.com/freeyoshino/url-shortener/blob/main/src/urls/dto/update-url.dto.ts"
click node_analytics_service "https://github.com/freeyoshino/url-shortener/blob/main/src/urls/analytics.service.ts"
click node_prisma_module "https://github.com/freeyoshino/url-shortener/blob/main/src/prisma/prisma.module.ts"
click node_prisma_service "https://github.com/freeyoshino/url-shortener/blob/main/src/prisma/prisma.service.ts"
click node_postgres "https://github.com/freeyoshino/url-shortener/blob/main/prisma/schema.prisma"
click node_rate_limit "https://github.com/freeyoshino/url-shortener/tree/main/src/urls"

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_url_api,node_redirect,node_rate_limit,node_user toneBlue
class node_url_service,node_create_dto,node_update_dto toneAmber
class node_analytics_service toneMint
class node_prisma_module,node_prisma_service,node_postgres toneRose
```

## Components

### HTTP API

- [URL API](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/urls.controller.ts): `src/urls/urls.controller.ts`
- [Redirect Handler](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/redirect.controller.ts): `src/urls/redirect.controller.ts`
- [Request Limiting](https://github.com/freeyoshino/url-shortener/tree/main/src/urls): `src/urls`

### URL Operations

- [URL Service](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/urls.service.ts): `src/urls/urls.service.ts`
- [Create URL Input](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/dto/create-url.dto.ts): `src/urls/dto/create-url.dto.ts`
- [Update URL Input](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/dto/update-url.dto.ts): `src/urls/dto/update-url.dto.ts`

### Click Analytics

- [Analytics Service](https://github.com/freeyoshino/url-shortener/blob/main/src/urls/analytics.service.ts): `src/urls/analytics.service.ts`

### Persistence

- [Prisma Module](https://github.com/freeyoshino/url-shortener/blob/main/src/prisma/prisma.module.ts): `src/prisma/prisma.module.ts`
- [Prisma Service](https://github.com/freeyoshino/url-shortener/blob/main/src/prisma/prisma.service.ts): `src/prisma/prisma.service.ts`
- [PostgreSQL](https://github.com/freeyoshino/url-shortener/blob/main/prisma/schema.prisma): `prisma/schema.prisma`

### Other components

- **User**

## Connections

- User → URL API: submits URL (evidence: `README.md`)
- User → Redirect Handler: visits short code (evidence: `README.md`)
- URL API → Create URL Input: accepts input (evidence: `src/urls/urls.controller.ts`)
- URL API → Update URL Input: accepts input (evidence: `src/urls/urls.controller.ts`)
- URL API → URL Service: delegates URL work (evidence: `src/urls/urls.controller.ts`)
- URL API → Analytics Service: requests statistics (evidence: `src/urls/urls.controller.ts`)
- Redirect Handler → URL Service: resolves short code (evidence: `src/urls/redirect.controller.ts`)
- Redirect Handler → Analytics Service: records click (evidence: `src/urls/redirect.controller.ts`)
- URL Service → Prisma Service: reads and writes URLs (evidence: `src/urls/urls.service.ts`)
- Analytics Service → Prisma Service: records and counts clicks (evidence: `src/urls/analytics.service.ts`)
- Prisma Module → Prisma Service: provides (evidence: `src/prisma/prisma.module.ts`)
- Prisma Service → PostgreSQL: connects to (evidence: `src/prisma/prisma.service.ts`)
- User → Request Limiting: may be throttled (evidence: `README.md`)
