# shreyasganesh911/swifturl architecture

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

- Interactive diagram: https://gitdiagram.com/shreyasganesh911/swifturl
- Repository: https://github.com/shreyasganesh911/swifturl

## Overview

##### Main Components
- Client/External User: Initiates URL shortening requests and analytics lookups.
- API Gateway/Server: The Node.js/Fastify web server handling incoming HTTP requests.
- Middleware Components:
- Rate Limiter (Redis based)
- JWT Authentication (auth middleware)
- Controllers: Handle the logic for API endpoints (e.g., user, URL, and analytics).
- Routes: Map endpoints to controllers (organized under /src/routes).
- Models & Database Layer:
- MongoDB for storing user and URL details
- Redis for caching (fast URL lookup) and implementing rate limiting.
- Utilities:
- Cloudinary integration for QR code generation.
- QR Code Generation Utility.
- Asynchronous request handling (error wrapper).
- External Services:
- MongoDB and Redis instances
- Cloudinary for media storage

##### Relationships and Interactions
- User Requests hit the Node.js/Fastify server through API endpoints (as defined in the routes).
- Requests are first processed by middleware (e.g., “rateLimiter” to check for abuse, “auth” for secure endpoints).
- If allowed, controllers process the request:
- They may call the caching utility to check if the URL is already in Redis.
- In case of a cache miss, the controller will interact with the MongoDB layer (using models and db modules) and then populate the Redis cache.
- For QR code functionalities, the utility handling Cloudinary integration is invoked.
- The README flowchart specifically illustrates how a request is checked against Redis first. If the data is present (cache hit), cached data is returned. Otherwise, the system queries MongoDB, updates Redis, and sends the response.
- Additionally, authentication-related endpoints use JWT tokens for managing sessions.

##### Architectural Patterns and Design Principles
- Modular Pattern: Clear separation of concerns (controllers, routes, middleware, db services).
- Caching Pattern: Use of Redis to improve response times and offload MongoDB queries.
- API Layer Abstraction: Cleanly defined RESTful endpoints.
- Security: JWT-based user authentication and rate limiting to mitigate abuse.
- Utility/Helper Functions: Centralized error and asynchronous handling as well as integration services (Cloudinary).

##### Diagramming Tools and Detail
- Including a side note or zoomed-in portion for the caching flow (as per the README’s flowchart) demonstrating how a URL shortening request is processed step-by-step.

## Diagram (Mermaid)

```mermaid
flowchart TD
    client["Client/External User"]:::client
    gateway["API Gateway (Fastify Server)"]:::server
    middleware_rl["Middleware: Rate Limiter"]:::middleware
    middleware_auth["Middleware: JWT Authentication"]:::middleware
    routes["Routes Mapping"]:::routesstyle
    controller_api["Controller: API Logic"]:::controller
    controller_url["Controller: URL"]:::controller
    controller_user["Controller: User"]:::controller
    model_url["Model: URL Data"]:::model
    model_user["Model: User Data"]:::model
    db_redis(("Redis – Cache & Rate Limiter")):::db
    db_mongo(("MongoDB – Persistent Storage")):::db
    utility_async["Utility: Async Error Handler"]:::utility
    utility_qr["Utility: QR Code Generation"]:::utility
    utility_cloudinary["Utility: Cloudinary Integration"]:::utility
    external_cloudinary(("Cloudinary (External Service)")):::external

    %% Flow connections
    client --> gateway
    gateway --> middleware_rl
    gateway --> middleware_auth
    middleware_rl --> routes
    middleware_auth --> routes

    routes --> controller_api
    routes --> controller_url
    routes --> controller_user

    %% Middleware rate limiter uses Redis for rate limiting
    middleware_rl --> db_redis

    %% Controllers use async error handler
    controller_api --> utility_async
    controller_url --> utility_async
    controller_user --> utility_async

    %% Controllers check cache first
    controller_api --> db_redis
    controller_url --> db_redis
    controller_user --> db_redis

    %% On cache miss, controllers fallback to MongoDB and then update cache
    controller_api -- "cacheMiss" --> db_mongo
    controller_url -- "cacheMiss" --> db_mongo
    controller_user -- "cacheMiss" --> db_mongo
    db_mongo -. "updateCache" .-> db_redis

    %% Controllers call models for data operations
    controller_url --> model_url
    controller_user --> model_user

    %% URL Controller invokes QR code related utilities
    controller_url --> utility_qr
    utility_qr --> utility_cloudinary
    utility_cloudinary --> external_cloudinary

    %% Click Events
    click gateway "https://github.com/shreyasganesh911/swifturl/blob/master/src/app.ts"
    click gateway "https://github.com/shreyasganesh911/swifturl/blob/master/src/index.ts"
    click middleware_rl "https://github.com/shreyasganesh911/swifturl/blob/master/src/middleware/rateLimiter.ts"
    click middleware_auth "https://github.com/shreyasganesh911/swifturl/blob/master/src/middleware/auth.ts"
    click controller_api "https://github.com/shreyasganesh911/swifturl/blob/master/src/controllers/api.controller.ts"
    click controller_url "https://github.com/shreyasganesh911/swifturl/blob/master/src/controllers/url.controller.ts"
    click controller_user "https://github.com/shreyasganesh911/swifturl/blob/master/src/controllers/user.controller.ts"
    click routes "https://github.com/shreyasganesh911/swifturl/blob/master/src/routes/api.route.ts"
    click routes "https://github.com/shreyasganesh911/swifturl/blob/master/src/routes/url.route.ts"
    click routes "https://github.com/shreyasganesh911/swifturl/blob/master/src/routes/user.route.ts"
    click model_url "https://github.com/shreyasganesh911/swifturl/blob/master/src/models/url.model.ts"
    click model_user "https://github.com/shreyasganesh911/swifturl/blob/master/src/models/user.model.ts"
    click db_mongo "https://github.com/shreyasganesh911/swifturl/blob/master/src/db/mongo.ts"
    click db_redis "https://github.com/shreyasganesh911/swifturl/blob/master/src/db/redis.ts"
    click utility_cloudinary "https://github.com/shreyasganesh911/swifturl/blob/master/src/utils/Cloudinary.ts"
    click utility_qr "https://github.com/shreyasganesh911/swifturl/blob/master/src/utils/GenerateQR.ts"
    click utility_async "https://github.com/shreyasganesh911/swifturl/blob/master/src/utils/Asynchandler.ts"

    %% Styling Classes
    classDef client fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef middleware fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef routesstyle fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef controller fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef model fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef db fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef utility fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef external fill:#E0FFFF,stroke:#333,stroke-width:2px;

    class client client;
    class gateway server;
    class middleware_rl,middleware_auth middleware;
    class routes routesstyle;
    class controller_api,controller_url,controller_user controller;
    class model_url,model_user model;
    class db_redis,db_mongo db;
    class utility_async,utility_qr,utility_cloudinary utility;
    class external_cloudinary external;
```
