# vimaneti-ai/ai-url-shortener architecture

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

- Interactive diagram: https://gitdiagram.com/vimaneti-ai/ai-url-shortener
- Repository: https://github.com/vimaneti-ai/ai-url-shortener

## Overview

This is a full-stack URL shortener: users create, manage, and inspect short links in an Angular UI, while visitors resolve codes through a redirect endpoint. The documented runtime also includes cached lookups, asynchronous click-event persistence and geolocation, expiry cleanup, rate limiting, and internal metrics. The README provides the redirect/Kafka flow; sampled frontend code confirms the UI-to-API calls. Backend details not sampled are included only where README capabilities or documented architecture support them.

Main entry points: [`src/main/java/com/example/URLShortener/controllers/urlController.java`](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/controllers/urlController.java) (URL controller), [`src/main/java/com/example/URLShortener/services/UrlService.java`](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/UrlService.java) (URL service), [`src/main/java/com/example/URLShortener/services/ClickEventConsumer.java`](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/ClickEventConsumer.java) (Click consumer), [`src/main/java/com/example/URLShortener/repository/UrlRepository.java`](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/repository/UrlRepository.java) (URL repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_ui_app["Angular app<br/>[app.component.ts]"]
  node_ui_api["API client<br/>[api.service.ts]"]
end

subgraph group_links["Link operations"]
  node_controller["URL controller<br/>[urlController.java]"]
  node_url_service["URL service<br/>[UrlService.java]"]
  node_validator["URL validation"]
  node_encoder["Base62 codes<br/>[Base62Encoder.java]"]
  node_url_repo["URL repository<br/>[UrlRepository.java]"]
  node_cleanup["Expiry cleanup"]
end

subgraph group_analytics["Click analytics"]
  node_kafka["Kafka events<br/>[KafkaConfig.java]"]
  node_click_consumer["Click consumer"]
  node_geoip["GeoIP lookup<br/>[GeoIpService.java]"]
  node_analytics_service["Analytics service"]
  node_click_repo["Click repository"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_cache[("Redis cache")]
  node_postgres[("PostgreSQL")]
  node_rate_filter["Rate limiter"]
  node_prometheus["Prometheus<br/>[prometheus.yml]"]
  node_grafana["Grafana dashboard<br/>[url-shortener.json]"]
end

node_browser(("Browser"))
node_geo_provider(("GeoIP provider"))

node_browser -->|"uses UI"| node_ui_app
node_ui_app -->|"requests API"| node_ui_api
node_ui_api -->|"calls endpoints"| node_controller
node_browser -->|"requests redirect"| node_controller
node_rate_filter -->|"filters requests"| node_controller
node_controller -->|"handles links"| node_url_service
node_url_service -->|"validates URL"| node_validator
node_url_service -->|"generates code"| node_encoder
node_url_service -->|"reads/writes"| node_cache
node_url_service -->|"queries links"| node_url_repo
node_url_repo -->|"reads/writes"| node_postgres
node_controller -->|"publishes clicks"| node_kafka
node_kafka -->|"dispatches events"| node_click_consumer
node_click_consumer -->|"resolves visitor"| node_geoip
node_geoip -.->|"queries location"| node_geo_provider
node_click_consumer -->|"persists events"| node_click_repo
node_click_repo -->|"writes events"| node_postgres
node_controller -->|"requests analytics"| node_analytics_service
node_analytics_service -->|"queries clicks"| node_click_repo
node_cleanup -->|"removes expired"| node_url_repo
node_cleanup -->|"clears entries"| node_cache
node_prometheus -->|"feeds dashboards"| node_grafana

click node_ui_app "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/frontend/src/app/app.component.ts"
click node_ui_api "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/frontend/src/app/services/api.service.ts"
click node_controller "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/controllers/urlController.java"
click node_url_service "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/UrlService.java"
click node_validator "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/validation/HttpUrlValidator.java"
click node_encoder "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/Base62Encoder.java"
click node_url_repo "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/repository/UrlRepository.java"
click node_rate_filter "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/config/RateLimitFilter.java"
click node_kafka "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/config/KafkaConfig.java"
click node_click_consumer "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/ClickEventConsumer.java"
click node_geoip "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/GeoIpService.java"
click node_analytics_service "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/AnalyticsService.java"
click node_click_repo "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/repository/ClickEventRepository.java"
click node_cleanup "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/CleanupService.java"
click node_prometheus "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/monitoring/prometheus.yml"
click node_grafana "https://github.com/vimaneti-ai/ai-url-shortener/blob/main/monitoring/grafana/provisioning/dashboards/url-shortener.json"

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_ui_app,node_ui_api,node_browser toneBlue
class node_controller,node_url_service,node_validator,node_encoder,node_url_repo,node_cleanup toneAmber
class node_kafka,node_click_consumer,node_geoip,node_analytics_service,node_click_repo toneMint
class node_cache,node_postgres,node_rate_filter,node_prometheus,node_grafana toneRose
class node_geo_provider toneIndigo
```

## Components

### Web interface

- [Angular app](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/frontend/src/app/app.component.ts): `frontend/src/app/app.component.ts`
- [API client](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/frontend/src/app/services/api.service.ts): `frontend/src/app/services/api.service.ts`

### Link operations

- [URL controller](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/controllers/urlController.java): `src/main/java/com/example/URLShortener/controllers/urlController.java`
- [URL service](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/UrlService.java): `src/main/java/com/example/URLShortener/services/UrlService.java`
- [URL validation](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/validation/HttpUrlValidator.java): `src/main/java/com/example/URLShortener/validation/HttpUrlValidator.java`
- [Base62 codes](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/Base62Encoder.java): `src/main/java/com/example/URLShortener/services/Base62Encoder.java`
- [URL repository](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/repository/UrlRepository.java): `src/main/java/com/example/URLShortener/repository/UrlRepository.java`
- [Expiry cleanup](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/CleanupService.java): `src/main/java/com/example/URLShortener/services/CleanupService.java`

### Click analytics

- [Kafka events](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/config/KafkaConfig.java): `src/main/java/com/example/URLShortener/config/KafkaConfig.java`
- [Click consumer](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/ClickEventConsumer.java): `src/main/java/com/example/URLShortener/services/ClickEventConsumer.java`
- [GeoIP lookup](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/GeoIpService.java): `src/main/java/com/example/URLShortener/services/GeoIpService.java`
- [Analytics service](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/services/AnalyticsService.java): `src/main/java/com/example/URLShortener/services/AnalyticsService.java`
- [Click repository](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/repository/ClickEventRepository.java): `src/main/java/com/example/URLShortener/repository/ClickEventRepository.java`

### Runtime infrastructure

- **Redis cache**
- **PostgreSQL**
- [Rate limiter](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/src/main/java/com/example/URLShortener/config/RateLimitFilter.java): `src/main/java/com/example/URLShortener/config/RateLimitFilter.java`
- [Prometheus](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/monitoring/prometheus.yml): `monitoring/prometheus.yml`
- [Grafana dashboard](https://github.com/vimaneti-ai/ai-url-shortener/blob/main/monitoring/grafana/provisioning/dashboards/url-shortener.json): `monitoring/grafana/provisioning/dashboards/url-shortener.json`

### Other components

- **Browser**
- **GeoIP provider**

## Connections

- Browser → Angular app: uses UI
- Angular app → API client: requests API
- API client → URL controller: calls endpoints
- Browser → URL controller: requests redirect
- Rate limiter → URL controller: filters requests
- URL controller → URL service: handles links
- URL service → URL validation: validates URL
- URL service → Base62 codes: generates code
- URL service → Redis cache: reads/writes
- URL service → URL repository: queries links
- URL repository → PostgreSQL: reads/writes
- URL controller → Kafka events: publishes clicks
- Kafka events → Click consumer: dispatches events
- Click consumer → GeoIP lookup: resolves visitor
- GeoIP lookup → GeoIP provider: queries location
- Click consumer → Click repository: persists events
- Click repository → PostgreSQL: writes events
- URL controller → Analytics service: requests analytics
- Analytics service → Click repository: queries clicks
- Expiry cleanup → URL repository: removes expired
- Expiry cleanup → Redis cache: clears entries
- Prometheus → Grafana dashboard: feeds dashboards