# nagavjm/shortlink architecture

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

- Interactive diagram: https://gitdiagram.com/nagavjm/shortlink
- Repository: https://github.com/nagavjm/shortlink

## Overview

ShortLink is a URL-shortening product with an Angular client and an ASP.NET API. Users create links, browse paginated mappings, deactivate links, or follow a short link to its destination; redirects also enqueue click tracking. The application service coordinates validation, code generation, persistence, caching, and analytics. The sampled source supports the main API and service calls, repository persistence, and cache behavior. Some infrastructure wiring and the client’s HTTP-to-API connection are not shown, so those links are omitted or marked unverified.

Main entry points: [`src/ShortLink.Application/Services/UrlShortenerService.cs`](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Application/Services/UrlShortenerService.cs) (URL use cases), [`client/src/app/app.component.ts`](https://github.com/nagavjm/shortlink/blob/main/client/src/app/app.component.ts) (ShortLink UI), [`src/ShortLink.Infrastructure/Data/Repositories/UrlMappingRepository.cs`](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Data/Repositories/UrlMappingRepository.cs) (Mapping repository), [`client/src/app/services/url-shortener.service.ts`](https://github.com/nagavjm/shortlink/blob/main/client/src/app/services/url-shortener.service.ts) (URL client service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["ShortLink UI<br/>[app.component.ts]"]
  node_webservice["URL client service"]
  node_urlmodel["URL models<br/>[url.model.ts]"]
end

subgraph group_api["API"]
  node_urlsapi["URL management API<br/>[UrlsController.cs]"]
  node_redirectapi["Redirect endpoint"]
  node_exception["Exception handling"]
end

subgraph group_application["Application workflows"]
  node_shortener["URL use cases"]
  node_validator["Request validation"]
  node_mapping["URL mapping entity<br/>[UrlMapping.cs]"]
end

subgraph group_infrastructure["Infrastructure and state"]
  node_codegen["Short-code generation"]
  node_base62["Base62 encoding<br/>[Base62Service.cs]"]
  node_repository["Mapping repository"]
  node_dbcontext["EF data context"]
  node_cache["Redis cache adapter"]
  node_clickqueue["Click analytics queue"]
  node_worker["Analytics worker"]
end

node_visitor(("Link user"))
node_apiuser(("API caller"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_visitor -->|"uses"| node_webapp
node_webapp -->|"requests links"| node_webservice
node_webapp -->|"uses types"| node_urlmodel
node_webapp -->|"deactivates links"| node_webservice
node_webservice -->|"uses types"| node_urlmodel
node_apiuser -->|"manages links"| node_urlsapi
node_apiuser -->|"follows short link"| node_redirectapi
node_urlsapi -->|"invokes use cases"| node_shortener
node_redirectapi -->|"resolves destination"| node_shortener
node_shortener -->|"reads and writes mappings"| node_repository
node_shortener -->|"looks up and warms cache"| node_cache
node_shortener -.->|"generates short code"| node_codegen
node_codegen -.->|"encodes identifier"| node_base62
node_shortener -->|"creates and updates"| node_mapping
node_repository -->|"reads and persists"| node_mapping
node_repository -->|"queries and saves"| node_dbcontext
node_dbcontext -.->|"stores mappings"| node_postgres
node_cache -->|"reads and writes"| node_redis
node_shortener -->|"enqueues clicks"| node_clickqueue
node_worker -->|"consumes events"| node_clickqueue
node_worker -->|"updates analytics"| node_dbcontext
node_exception -.->|"handles failures"| node_shortener

click node_webapp "https://github.com/nagavjm/shortlink/blob/main/client/src/app/app.component.ts"
click node_webservice "https://github.com/nagavjm/shortlink/blob/main/client/src/app/services/url-shortener.service.ts"
click node_urlmodel "https://github.com/nagavjm/shortlink/blob/main/client/src/app/models/url.model.ts"
click node_urlsapi "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.API/Controllers/UrlsController.cs"
click node_redirectapi "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.API/Controllers/RedirectController.cs"
click node_exception "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.API/Middleware/ExceptionHandlingMiddleware.cs"
click node_shortener "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Application/Services/UrlShortenerService.cs"
click node_validator "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Application/Validators/CreateUrlRequestValidator.cs"
click node_mapping "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Domain/Entities/UrlMapping.cs"
click node_codegen "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Services/AutoIncrementShortCodeGenerator.cs"
click node_base62 "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Services/Base62Service.cs"
click node_repository "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Data/Repositories/UrlMappingRepository.cs"
click node_dbcontext "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Data/ShortLinkDbContext.cs"
click node_cache "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Cache/RedisCacheService.cs"
click node_clickqueue "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Services/ClickAnalyticsChannel.cs"
click node_worker "https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/BackgroundServices/ClickAnalyticsBackgroundWorker.cs"

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_webapp,node_webservice,node_urlmodel,node_visitor toneBlue
class node_urlsapi,node_redirectapi,node_exception,node_postgres,node_redis toneAmber
class node_shortener,node_validator,node_mapping,node_apiuser toneMint
class node_codegen,node_base62,node_repository,node_dbcontext,node_cache,node_clickqueue,node_worker toneRose
```

## Components

### Web client

- [ShortLink UI](https://github.com/nagavjm/shortlink/blob/main/client/src/app/app.component.ts): `client/src/app/app.component.ts`
- [URL client service](https://github.com/nagavjm/shortlink/blob/main/client/src/app/services/url-shortener.service.ts): `client/src/app/services/url-shortener.service.ts`
- [URL models](https://github.com/nagavjm/shortlink/blob/main/client/src/app/models/url.model.ts): `client/src/app/models/url.model.ts`

### API

- [URL management API](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.API/Controllers/UrlsController.cs): `src/ShortLink.API/Controllers/UrlsController.cs`
- [Redirect endpoint](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.API/Controllers/RedirectController.cs): `src/ShortLink.API/Controllers/RedirectController.cs`
- [Exception handling](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.API/Middleware/ExceptionHandlingMiddleware.cs): `src/ShortLink.API/Middleware/ExceptionHandlingMiddleware.cs`

### Application workflows

- [URL use cases](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Application/Services/UrlShortenerService.cs): `src/ShortLink.Application/Services/UrlShortenerService.cs`
- [Request validation](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Application/Validators/CreateUrlRequestValidator.cs): `src/ShortLink.Application/Validators/CreateUrlRequestValidator.cs`
- [URL mapping entity](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Domain/Entities/UrlMapping.cs): `src/ShortLink.Domain/Entities/UrlMapping.cs`

### Infrastructure and state

- [Short-code generation](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Services/AutoIncrementShortCodeGenerator.cs): `src/ShortLink.Infrastructure/Services/AutoIncrementShortCodeGenerator.cs`
- [Base62 encoding](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Services/Base62Service.cs): `src/ShortLink.Infrastructure/Services/Base62Service.cs`
- [Mapping repository](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Data/Repositories/UrlMappingRepository.cs): `src/ShortLink.Infrastructure/Data/Repositories/UrlMappingRepository.cs`
- [EF data context](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Data/ShortLinkDbContext.cs): `src/ShortLink.Infrastructure/Data/ShortLinkDbContext.cs`
- [Redis cache adapter](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Cache/RedisCacheService.cs): `src/ShortLink.Infrastructure/Cache/RedisCacheService.cs`
- [Click analytics queue](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/Services/ClickAnalyticsChannel.cs): `src/ShortLink.Infrastructure/Services/ClickAnalyticsChannel.cs`
- [Analytics worker](https://github.com/nagavjm/shortlink/blob/main/src/ShortLink.Infrastructure/BackgroundServices/ClickAnalyticsBackgroundWorker.cs): `src/ShortLink.Infrastructure/BackgroundServices/ClickAnalyticsBackgroundWorker.cs`

### Other components

- **Link user**
- **API caller**
- **PostgreSQL**
- **Redis**

## Connections

- Link user → ShortLink UI: uses (evidence: `client/src/app/app.component.ts`)
- ShortLink UI → URL client service: requests links (evidence: `client/src/app/app.component.ts`)
- ShortLink UI → URL models: uses types (evidence: `client/src/app/app.component.ts`)
- ShortLink UI → URL client service: deactivates links (evidence: `client/src/app/app.component.ts`)
- URL client service → URL models: uses types (evidence: `client/src/app/services/url-shortener.service.ts`)
- API caller → URL management API: manages links (evidence: `src/ShortLink.API/Controllers/UrlsController.cs`)
- API caller → Redirect endpoint: follows short link (evidence: `src/ShortLink.API/Controllers/RedirectController.cs`)
- URL management API → URL use cases: invokes use cases (evidence: `src/ShortLink.API/Controllers/UrlsController.cs`)
- Redirect endpoint → URL use cases: resolves destination (evidence: `src/ShortLink.API/Controllers/RedirectController.cs`)
- URL use cases → Mapping repository: reads and writes mappings (evidence: `src/ShortLink.Application/Services/UrlShortenerService.cs`)
- URL use cases → Redis cache adapter: looks up and warms cache (evidence: `src/ShortLink.Application/Services/UrlShortenerService.cs`)
- URL use cases → Short-code generation: generates short code
- Short-code generation → Base62 encoding: encodes identifier
- URL use cases → URL mapping entity: creates and updates (evidence: `src/ShortLink.Application/Services/UrlShortenerService.cs`)
- Mapping repository → URL mapping entity: reads and persists (evidence: `src/ShortLink.Infrastructure/Data/Repositories/UrlMappingRepository.cs`)
- Mapping repository → EF data context: queries and saves (evidence: `src/ShortLink.Infrastructure/Data/Repositories/UrlMappingRepository.cs`)
- EF data context → PostgreSQL: stores mappings
- Redis cache adapter → Redis: reads and writes (evidence: `src/ShortLink.Infrastructure/Cache/RedisCacheService.cs`)
- URL use cases → Click analytics queue: enqueues clicks (evidence: `src/ShortLink.Application/Services/UrlShortenerService.cs`)
- Analytics worker → Click analytics queue: consumes events (evidence: `src/ShortLink.Infrastructure/BackgroundServices/ClickAnalyticsBackgroundWorker.cs`)
- Analytics worker → EF data context: updates analytics (evidence: `src/ShortLink.Infrastructure/BackgroundServices/ClickAnalyticsBackgroundWorker.cs`)
- Exception handling → URL use cases: handles failures
