# bhargavmupparisetty/trackable-pages architecture

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

- Interactive diagram: https://gitdiagram.com/bhargavmupparisetty/trackable-pages
- Repository: https://github.com/bhargavmupparisetty/trackable-pages

## Overview

##### Project type and purpose
- This is a small full-stack web application (“Trackable Pages”) whose sole purpose is to generate one-time, trackable short links for any legitimate URL, log visitor data (IP, device, geolocation), and then seamlessly redirect the visitor to the original URL.

##### File structure
- Top-level files:
- package.json / package-lock.json: Node.js dependencies
- server.js: the Express-based HTTP server entry point
- public/index.html: single-page UI for entering a URL
- node_modules: installed libraries (likely including Express, a geolocation library or HTTP-client, etc.)
- No database directory—logging is likely in memory, to disk, or via a third-party API.

##### README for additional insights
- Tech stack: HTML/Vanilla JS front end, Node.js backend
- Workflow: generate link → share link → log on click → redirect
- Potential external dependency: a geolocation API to map IP → location

A. Client Browser (frontend)
- Loads index.html
- Makes REST call to backend to “create” a trackable link
B. Backend Application (Node.js/Express)
- Link Generation Module
- Generates a unique token/URL for each submitted target URL
- Persists the (token → original-URL) mapping (in memory, file, or DB)
- Redirect & Tracking Module
- Receives incoming GET /track/:token requests
- Extracts client IP and User-Agent
- Calls Geolocation Service (internal library or external API) to resolve location
- Logs the aggregated data (IP, device, timestamp, resolved location)
- Responds with HTTP 302 redirect to the original URL
C. Storage (optional in your current implementation)
- In-memory store, file-based logs, or a future database (Mongo, Redis, etc.)
D. External Services
- Geolocation API (e.g., ip-api.com or a similar service)
- The legitimate target website (final redirect destination)

##### Architectural patterns and design principles
- Separation of concerns:
- UI layer in /public vs. server logic in server.js
- Link generation vs. redirect/tracking modules
- Stateless HTTP services: each redirect request carries all info in request headers
- Potential extension to microservices: e.g., a dedicated geolocation microservice or a database microservice

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Frontend
    Browser["User Browser"]:::ui
    UI["Frontend UI<br/>(public/index.html)"]:::ui

    %% Backend Subsystem
    subgraph "Backend (server.js)" 
        direction TB
        LinkGen["Link Generation Module<br/>POST /create"]:::biz
        Redirect["Redirect & Tracking Module<br/>GET /track/:token"]:::biz
    end

    %% Storage
    Storage["In-Memory Store / Logs"]:::data

    %% External Services
    GeoIP["Geolocation API"]:::external
    Target["Target Website"]:::external

    %% Dependencies & Documentation
    Docs["Project Docs<br/>(README.md)"]:::meta
    Deps["Dependencies & Scripts<br/>(package.json, package-lock.json)"]:::meta
    Libs["Installed Libraries<br/>(node_modules)"]:::meta

    %% Flows
    Browser -->|"Loads index.html"| UI
    UI -->|"HTTP POST JSON { originalUrl } to /create"| LinkGen
    LinkGen -->|"Stores token→URL"| Storage
    LinkGen -->|"Returns trackable URL"| UI
    UI -->|"Displays URL to User"| Browser

    Browser -->|"Clicks https://domain/track/:token"| Redirect
    Redirect -->|"Reads token, looks up URL"| Storage
    Redirect -->|"Extract IP, UA"| Redirect
    Redirect -->|"HTTP GET to GeoIP service"| GeoIP
    GeoIP -->|"Returns location data"| Redirect
    Redirect -->|"Logs data"| Storage
    Redirect -->|"HTTP 302 Location: originalUrl"| Target

    %% Click Events
    click UI "https://github.com/bhargavmupparisetty/trackable-pages/blob/master/public/index.html"
    click LinkGen "https://github.com/bhargavmupparisetty/trackable-pages/blob/master/server.js"
    click Redirect "https://github.com/bhargavmupparisetty/trackable-pages/blob/master/server.js"
    click Docs "https://github.com/bhargavmupparisetty/trackable-pages/blob/master/README.md"
    click Deps "https://github.com/bhargavmupparisetty/trackable-pages/blob/master/package.json"
    click Deps "https://github.com/bhargavmupparisetty/trackable-pages/blob/master/package-lock.json"
    click Libs "https://github.com/bhargavmupparisetty/trackable-pages/tree/master/node_modules"

    %% Styles
    classDef ui fill:#b3cde0,stroke:#2b5797,color:#000
    classDef biz fill:#ccebc5,stroke:#4f8a10,color:#000
    classDef data fill:#fbb4ae,stroke:#d00000,color:#000
    classDef external fill:#d9d9d9,stroke:#555,color:#000
    classDef meta fill:#decbe4,stroke:#64006a,color:#000
```
