# harshit3011/url-shortener architecture

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

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

## Overview

This repository is a Go/Gin URL-shortener backend; the Client directory is only a placeholder. The main workflows are account registration/login and authenticated URL creation/listing, plus shortcode redirects with click recording. Redirects check Redis first and on a miss look up MongoDB and cache the mapping; clicks are persisted and published to Kafka for downstream consumption. The graph also shows token-based route protection and rate limiting. Unexcerpted modules are included only where the README or source index supports them; connections without visible evidence are omitted.

Main entry points: [`Server/controllers/url.controllers.go`](https://github.com/harshit3011/url-shortener/blob/main/Server/controllers/url.controllers.go) (URL handlers), [`Server/routes/routes.go`](https://github.com/harshit3011/url-shortener/blob/main/Server/routes/routes.go) (HTTP routes), [`Server/controllers/user.controllers.go`](https://github.com/harshit3011/url-shortener/blob/main/Server/controllers/user.controllers.go) (Account handlers), [`Server/database/database.connection.go`](https://github.com/harshit3011/url-shortener/blob/main/Server/database/database.connection.go) (Mongo access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_routes["HTTP routes<br/>[routes.go]"]
end

subgraph group_identity["Identity and Access"]
  node_user_handlers["Account handlers"]
  node_auth["Auth middleware<br/>[auth.middleware.go]"]
  node_rate_limit["Rate limiting<br/>[rateLimiter.go]"]
  node_tokens["Token utilities<br/>[tokenUtility.go]"]
  node_user_model["User model<br/>[user.model.go]"]
end

subgraph group_url["URL and Clicks"]
  node_url_handlers["URL handlers<br/>[url.controllers.go]"]
  node_url_model["URL model<br/>[url.model.go]"]
  node_click_model["Click model<br/>[click.model.go]"]
  node_counter_model["Counter model<br/>[counters.model.go]"]
end

subgraph group_storage["Persistence and Events"]
  node_mongo_access["Mongo access"]
  node_mongo_indexes["Mongo indexes<br/>[indexes.go]"]
  node_mongo[("MongoDB")]
  node_redis_access["Redis access<br/>[redis.go]"]
  node_redis[("Redis")]
  node_producer["Click producer<br/>[producer.go]"]
  node_consumer["Click consumer<br/>[consumer.go]"]
  node_kafka["Kafka broker"]
end

subgraph group_runtime["Service Runtime"]
  node_main["Service startup<br/>[main.go]"]
  node_observability["Request observability"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_routes
node_main -->|"registers routes"| node_routes
node_main -->|"installs middleware"| node_observability
node_routes -->|"routes auth"| node_user_handlers
node_routes -->|"routes URLs"| node_url_handlers
node_routes -->|"protects routes"| node_auth
node_routes -->|"limits shortening"| node_rate_limit
node_user_handlers -->|"reads and writes"| node_mongo_access
node_url_handlers -->|"reads and writes"| node_mongo_access
node_user_handlers -->|"generates tokens"| node_tokens
node_auth -->|"validates tokens"| node_tokens
node_tokens -->|"checks session"| node_mongo_access
node_rate_limit -->|"increments limit"| node_redis_access
node_url_handlers -->|"caches redirects"| node_redis_access
node_mongo_access -->|"connects"| node_mongo
node_mongo_indexes -.->|"indexes collections"| node_mongo
node_redis_access -->|"connects"| node_redis
node_url_handlers -->|"publishes clicks"| node_producer
node_producer -->|"writes events"| node_kafka
node_main -->|"starts consumer"| node_consumer
node_consumer -->|"reads events"| node_kafka
node_user_handlers -->|"uses account data"| node_user_model
node_url_handlers -->|"uses URL data"| node_url_model
node_url_handlers -->|"creates click records"| node_click_model
node_url_handlers -->|"increments shortcode counter"| node_counter_model

click node_main "https://github.com/harshit3011/url-shortener/blob/main/Server/main.go"
click node_routes "https://github.com/harshit3011/url-shortener/blob/main/Server/routes/routes.go"
click node_observability "https://github.com/harshit3011/url-shortener/tree/main/Server/middleware"
click node_user_handlers "https://github.com/harshit3011/url-shortener/blob/main/Server/controllers/user.controllers.go"
click node_url_handlers "https://github.com/harshit3011/url-shortener/blob/main/Server/controllers/url.controllers.go"
click node_auth "https://github.com/harshit3011/url-shortener/blob/main/Server/middleware/auth.middleware.go"
click node_rate_limit "https://github.com/harshit3011/url-shortener/blob/main/Server/middleware/rateLimiter.go"
click node_tokens "https://github.com/harshit3011/url-shortener/blob/main/Server/utils/tokenUtility.go"
click node_user_model "https://github.com/harshit3011/url-shortener/blob/main/Server/models/user.model.go"
click node_url_model "https://github.com/harshit3011/url-shortener/blob/main/Server/models/url.model.go"
click node_click_model "https://github.com/harshit3011/url-shortener/blob/main/Server/models/click.model.go"
click node_counter_model "https://github.com/harshit3011/url-shortener/blob/main/Server/models/counters.model.go"
click node_mongo_access "https://github.com/harshit3011/url-shortener/blob/main/Server/database/database.connection.go"
click node_mongo_indexes "https://github.com/harshit3011/url-shortener/blob/main/Server/database/indexes.go"
click node_redis_access "https://github.com/harshit3011/url-shortener/blob/main/Server/database/redis.go"
click node_producer "https://github.com/harshit3011/url-shortener/blob/main/Server/kafka/producer.go"
click node_consumer "https://github.com/harshit3011/url-shortener/blob/main/Server/kafka/consumer.go"

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_routes,node_client toneBlue
class node_user_handlers,node_auth,node_rate_limit,node_tokens,node_user_model toneAmber
class node_url_handlers,node_url_model,node_click_model,node_counter_model toneMint
class node_mongo_access,node_mongo_indexes,node_mongo,node_redis_access,node_redis,node_producer,node_consumer,node_kafka toneRose
class node_main,node_observability toneIndigo
```

## Components

### HTTP API

- [HTTP routes](https://github.com/harshit3011/url-shortener/blob/main/Server/routes/routes.go): `Server/routes/routes.go`

### Identity and Access

- [Account handlers](https://github.com/harshit3011/url-shortener/blob/main/Server/controllers/user.controllers.go): `Server/controllers/user.controllers.go`
- [Auth middleware](https://github.com/harshit3011/url-shortener/blob/main/Server/middleware/auth.middleware.go): `Server/middleware/auth.middleware.go`
- [Rate limiting](https://github.com/harshit3011/url-shortener/blob/main/Server/middleware/rateLimiter.go): `Server/middleware/rateLimiter.go`
- [Token utilities](https://github.com/harshit3011/url-shortener/blob/main/Server/utils/tokenUtility.go): `Server/utils/tokenUtility.go`
- [User model](https://github.com/harshit3011/url-shortener/blob/main/Server/models/user.model.go): `Server/models/user.model.go`

### URL and Clicks

- [URL handlers](https://github.com/harshit3011/url-shortener/blob/main/Server/controllers/url.controllers.go): `Server/controllers/url.controllers.go`
- [URL model](https://github.com/harshit3011/url-shortener/blob/main/Server/models/url.model.go): `Server/models/url.model.go`
- [Click model](https://github.com/harshit3011/url-shortener/blob/main/Server/models/click.model.go): `Server/models/click.model.go`
- [Counter model](https://github.com/harshit3011/url-shortener/blob/main/Server/models/counters.model.go): `Server/models/counters.model.go`

### Persistence and Events

- [Mongo access](https://github.com/harshit3011/url-shortener/blob/main/Server/database/database.connection.go): `Server/database/database.connection.go`
- [Mongo indexes](https://github.com/harshit3011/url-shortener/blob/main/Server/database/indexes.go): `Server/database/indexes.go`
- **MongoDB**
- [Redis access](https://github.com/harshit3011/url-shortener/blob/main/Server/database/redis.go): `Server/database/redis.go`
- **Redis**
- [Click producer](https://github.com/harshit3011/url-shortener/blob/main/Server/kafka/producer.go): `Server/kafka/producer.go`
- [Click consumer](https://github.com/harshit3011/url-shortener/blob/main/Server/kafka/consumer.go): `Server/kafka/consumer.go`
- **Kafka broker**

### Service Runtime

- [Service startup](https://github.com/harshit3011/url-shortener/blob/main/Server/main.go): `Server/main.go`
- [Request observability](https://github.com/harshit3011/url-shortener/tree/main/Server/middleware): `Server/middleware`

### Other components

- **API client**

## Connections

- API client → HTTP routes: sends requests (evidence: `README.md`)
- Service startup → HTTP routes: registers routes (evidence: `Server/main.go`)
- Service startup → Request observability: installs middleware (evidence: `Server/main.go`)
- HTTP routes → Account handlers: routes auth (evidence: `Server/routes/routes.go`)
- HTTP routes → URL handlers: routes URLs (evidence: `Server/routes/routes.go`)
- HTTP routes → Auth middleware: protects routes (evidence: `Server/routes/routes.go`)
- HTTP routes → Rate limiting: limits shortening (evidence: `Server/routes/routes.go`)
- Account handlers → Mongo access: reads and writes (evidence: `Server/controllers/user.controllers.go`)
- URL handlers → Mongo access: reads and writes (evidence: `Server/controllers/url.controllers.go`)
- Account handlers → Token utilities: generates tokens (evidence: `Server/controllers/user.controllers.go`)
- Auth middleware → Token utilities: validates tokens (evidence: `Server/middleware/auth.middleware.go`)
- Token utilities → Mongo access: checks session (evidence: `Server/utils/tokenUtility.go`)
- Rate limiting → Redis access: increments limit (evidence: `Server/middleware/rateLimiter.go`)
- URL handlers → Redis access: caches redirects (evidence: `Server/controllers/url.controllers.go`)
- Mongo access → MongoDB: connects (evidence: `README.md`)
- Mongo indexes → MongoDB: indexes collections
- Redis access → Redis: connects (evidence: `README.md`)
- URL handlers → Click producer: publishes clicks (evidence: `Server/controllers/url.controllers.go`)
- Click producer → Kafka broker: writes events (evidence: `Server/kafka/producer.go`)
- Service startup → Click consumer: starts consumer (evidence: `Server/main.go`)
- Click consumer → Kafka broker: reads events (evidence: `Server/kafka/consumer.go`)
- Account handlers → User model: uses account data (evidence: `Server/controllers/user.controllers.go`)
- URL handlers → URL model: uses URL data (evidence: `Server/controllers/url.controllers.go`)
- URL handlers → Click model: creates click records (evidence: `Server/controllers/url.controllers.go`)
- URL handlers → Counter model: increments shortcode counter (evidence: `Server/controllers/url.controllers.go`)