# ahmedasem1/url-shortener architecture

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

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

## Overview

##### Project type and purpose
- This is a backend-only, distributed URL-shortener service written in Go.
- It provides an HTTP API (no SPA/UI), with endpoints to shorten URLs, redirect to originals, test rate limits, and expose Swagger docs.
- It uses Redis for rate limiting and as an analytics queue, MongoDB for persistent URL and analytics storage, and is deployed via Docker/Kubernetes with a GitHub Actions CI/CD pipeline.

##### File structure
- Top-level: Dockerfiles, Compose, K8s manifests, and Go module files.
- src/ directory holds all Go code, split into:
- config/ – configuration loader
- docs/ – Swagger JSON/YAML and doc generator
- handlers/ – HTTP endpoint implementations
- middleware/ – Redis-backed rate limiter
- storage/ – Mongo and Redis clients
- workers/ – background analytics processor
- main.go – application entrypoint
- tests/ folder contains unit and integration tests.
- k8s/ folder defines separate deployments for API, Redis, Mongo, and nginx ingress.

##### README for additional insights
- Confirms tech stack: Go, Redis, MongoDB, Kubernetes, Docker Compose.
- Describes Docker-Compose for local dev, GitHub Actions for CI/CD (build/tests, Docker Hub push, K8s deploy).
- Provides environment variables, swagger endpoint, and basic usage.

##### Elements
- Clear, descriptive labels for each component (e.g. “API Service (Go)”, “Redis (Rate Limiter & Queue)”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["Client (HTTP)"]:::external

    %% Production Kubernetes Cluster
    subgraph "Production (Kubernetes)"
        direction TB
        Ingress["Ingress (NGINX)"]:::infra
        API["API Service (Go)"]:::compute
        Redis["Redis\n(Rate Limiter & Queue)"]:::datastore
        Mongo["MongoDB\n(Primary Data Store)"]:::datastore
        Worker["Analytics Worker"]:::compute
    end

    %% CI/CD Pipeline
    GitHub["GitHub Actions"]:::pipeline
    DockerHub["Docker Hub"]:::external

    %% Local Development
    subgraph "Local Development (Docker Compose)"
        direction TB
        NginxLocal["NGINX (Optional)"]:::infra
        API_Local["API Service (Go)"]:::compute
        Redis_Local["Redis"]:::datastore
        Mongo_Local["MongoDB"]:::datastore
    end

    %% Flows: Production
    Client -->|HTTP| Ingress
    Ingress -->|HTTP| API
    API -->|HTTP| Redis
    API -->|HTTP| Mongo
    API -->|LPUSH analytics| Redis
    Redis -->|LPOP tasks| Worker
    Worker -->|Write analytics| Mongo

    %% Flows: CI/CD
    GitHub -->|build & push| DockerHub
    DockerHub -->|kubectl apply| Ingress
    DockerHub -->|kubectl apply| API
    DockerHub -->|kubectl apply| Redis
    DockerHub -->|kubectl apply| Mongo
    DockerHub -->|kubectl apply| Worker

    %% Flows: Local Dev
    NginxLocal -->|HTTP| API_Local
    API_Local -->|HTTP| Redis_Local
    API_Local -->|HTTP| Mongo_Local

    %% Click Events
    click API "https://github.com/ahmedasem1/url-shortener/blob/main/src/main.go"
    click Ingress "https://github.com/ahmedasem1/url-shortener/blob/main/k8s/nginx-config.yaml"
    click Redis "https://github.com/ahmedasem1/url-shortener/blob/main/k8s/redis-deployment.yaml"
    click Mongo "https://github.com/ahmedasem1/url-shortener/blob/main/k8s/mongo-deployment.yaml"
    click Worker "https://github.com/ahmedasem1/url-shortener/blob/main/src/workers/analytics_worker.go"
    click GitHub "https://github.com/ahmedasem1/url-shortener/blob/main/.github/workflows/ci-cd.yml"
    click API_Local "https://github.com/ahmedasem1/url-shortener/blob/main/docker-compose.yml"

    %% Styles
    classDef compute fill:#D2E8FF,stroke:#004085,color:#004085;
    classDef datastore fill:#D1E7DD,stroke:#0F5132,color:#0F5132;
    classDef external fill:#FFF3CD,stroke:#856404,color:#856404;
    classDef infra fill:#E2E3E5,stroke:#6C757D,color:#6C757D;
    classDef pipeline fill:#F8D7DA,stroke:#842029,color:#842029;
```
