# raahthor/url-shortener architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack URL Shortener application built on the PERN stack (PostgreSQL, Express.js, React, Node.js).
- Its core purpose is to allow users (guests or registered) to shorten long URLs, track click statistics, and manage links via a web interface.

##### File structure
- Top-level directories:
- Backend – Express.js server with subdirectories for Controllers, DB, Models, and Routes.
- Frontend – React application with Tailwind CSS, Vite build, and component structure under src.
- Backend follows an MVC-style pattern:
- Controllers handle request logic (authenticator, URL storage, user storage).
- Models define ORM schemas for users and URLs (syncModels, users.model.js, urls.model.js).
- DB contains database initialization (database.js).
- Routes file (routes.js) maps HTTP endpoints to controllers.
- Frontend uses component-driven design:
- src/components holds UI pieces (forms, buttons, cards, routing pages).
- Utility functions (src/lib/utils.js) and Tailwind configuration manage styling.
- Config and deployment artifacts:
- Frontend/vite.config.js and Backend/package.json for builds.
- Frontend/vercel.json for Vercel deployment.

##### Extract insights from README
- Tech stack: React + Tailwind CSS on the client; Node + Express + JWT + bcrypt on the server; PostgreSQL as the persistent layer.
- Key functional areas: URL shortening API, user authentication (JWT, bcrypt), click-tracking analytics, guest versus registered modes.

a. Main components
- Client (React SPA)
- API Server (Node.js + Express.js)
- PostgreSQL Database
- Authentication subsystem (JWT issuance/verification, bcrypt hashing)
- Optional: External deployment platform (e.g., Vercel for frontend, Heroku/AWS for backend)
b. Relationships and data flows
- The React client issues HTTP(S) requests to Express endpoints:
– POST /signup, /login → handles user creation and token issuance
– POST /shorten → saves a new shortened URL
– GET /:shortId → redirects to original URL and increments click counter
– GET /stats → returns click statistics (authorized)
- Express communicates with PostgreSQL via an ORM or raw queries (database.js + syncModels).
- JWT tokens are generated by the authenticator controller and validated on protected routes.
c. Architectural patterns and principles
- MVC on the server: clear separation between routing (routes.js), business logic (controllers), and data models.
- Single-page application on the client: React components handle routing and UI state.
- RESTful API endpoints for CRUD operations on URLs and user sessions.
- Stateless authentication with JWT to allow horizontal scaling of the API.
d. Key technologies and libraries
- Frontend: React, Vite, Tailwind CSS, utility components (button, input, card).
- Backend: Express.js, pg or Sequelize/ORM layer (syncModels), jsonwebtoken, bcrypt.
- Database: PostgreSQL, with connection pooling in database.js.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (React SPA)"
        F_main["main.jsx"]:::frontend
        F_app["App.jsx"]:::frontend
        F_home["homePage.jsx"]:::frontend
        F_logged["loggedInPage.jsx"]:::frontend
        F_signup["signUpPage.jsx"]:::frontend
        subgraph "UI Components"
            FB_button["button.jsx"]:::frontend
            FB_card["card.jsx"]:::frontend
            FB_input["input.jsx"]:::frontend
            FB_label["label.jsx"]:::frontend
        end
        subgraph "Form & Features"
            F_loginForm["login-form.jsx"]:::frontend
            F_urlAnon["urlSection.jsx"]:::frontend
            F_urlAuth["urlSectionLogin.jsx"]:::frontend
            F_stats["userStats.jsx"]:::frontend
        end
        F_utils["utils.js"]:::frontend
        F_tail["tailwind.config.js"]:::frontend
        F_postcss["postcss.config.cjs"]:::frontend
        F_vite["vite.config.js"]:::frontend
        F_vercel["vercel.json"]:::frontend
    end

    subgraph "Backend (Express API)"
        BE_index["index.js"]:::backend
        BE_routes["routes.js"]:::backend
        subgraph "Controllers"
            BE_auth["authenticator.js"]:::backend
            BE_storeUrl["storeUrl.js"]:::backend
            BE_storeUser["storeUser.js"]:::backend
        end
        subgraph "DB & Models"
            BE_db["database.js"]:::backend
            BE_sync["syncModels.js"]:::backend
            BE_urlModel["urls.model.js"]:::backend
            BE_userModel["users.model.js"]:::backend
        end
        BE_pkg["package.json"]:::backend
    end

    DB["PostgreSQL"]:::db

    F_main -->|loads| F_app
    F_app -->|renders pages| F_home
    F_app -->|renders pages| F_logged
    F_app -->|renders pages| F_signup
    F_app -->|uses UI| FB_button
    F_app -->|uses UI| FB_card
    F_app -->|uses UI| FB_input
    F_app -->|uses UI| FB_label
    F_app -->|calls features| F_loginForm
    F_app -->|calls features| F_urlAnon
    F_app -->|calls features| F_urlAuth
    F_app -->|calls features| F_stats
    F_app -->|imports utils| F_utils
    F_app -->|HTTP requests| BE_routes

    BE_index -->|uses routes| BE_routes
    BE_routes -->|invoke| BE_auth
    BE_routes -->|invoke| BE_storeUrl
    BE_routes -->|invoke| BE_storeUser
    BE_auth -->|reads/writes| BE_db
    BE_storeUrl -->|reads/writes| BE_db
    BE_storeUser -->|reads/writes| BE_db
    BE_db -->|initializes| BE_sync
    BE_sync -->|defines| BE_urlModel
    BE_sync -->|defines| BE_userModel

    BE_auth -->|JWT & bcrypt| BE_pkg
    BE_routes -->|depends on| BE_pkg

    BE_db -->|connects to| DB
    BE_auth -->|connects to| DB
    BE_storeUrl -->|connects to| DB
    BE_storeUser -->|connects to| DB

    click F_main "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/main.jsx"
    click F_app "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/App.jsx"
    click F_home "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/RoutePages/homePage.jsx"
    click F_logged "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/RoutePages/loggedInPage.jsx"
    click F_signup "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/RoutePages/signUpPage.jsx"
    click FB_button "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/ui/button.jsx"
    click FB_card "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/ui/card.jsx"
    click FB_input "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/ui/input.jsx"
    click FB_label "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/ui/label.jsx"
    click F_loginForm "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/login-form.jsx"
    click F_urlAnon "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/urlSection.jsx"
    click F_urlAuth "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/urlSectionLogin.jsx"
    click F_stats "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/components/userStats.jsx"
    click F_utils "https://github.com/raahthor/url-shortener/blob/main/Frontend/src/lib/utils.js"
    click F_tail "https://github.com/raahthor/url-shortener/blob/main/Frontend/tailwind.config.js"
    click F_postcss "https://github.com/raahthor/url-shortener/blob/main/Frontend/postcss.config.cjs"
    click F_vite "https://github.com/raahthor/url-shortener/blob/main/Frontend/vite.config.js"
    click F_vercel "https://github.com/raahthor/url-shortener/blob/main/Frontend/vercel.json"
    click BE_index "https://github.com/raahthor/url-shortener/blob/main/Backend/index.js"
    click BE_routes "https://github.com/raahthor/url-shortener/blob/main/Backend/Routes/routes.js"
    click BE_auth "https://github.com/raahthor/url-shortener/blob/main/Backend/Controllers/authenticator.js"
    click BE_storeUrl "https://github.com/raahthor/url-shortener/blob/main/Backend/Controllers/storeUrl.js"
    click BE_storeUser "https://github.com/raahthor/url-shortener/blob/main/Backend/Controllers/storeUser.js"
    click BE_db "https://github.com/raahthor/url-shortener/blob/main/Backend/DB/database.js"
    click BE_sync "https://github.com/raahthor/url-shortener/blob/main/Backend/Models/syncModels.js"
    click BE_urlModel "https://github.com/raahthor/url-shortener/blob/main/Backend/Models/urls.model.js"
    click BE_userModel "https://github.com/raahthor/url-shortener/blob/main/Backend/Models/users.model.js"
    click BE_pkg "https://github.com/raahthor/url-shortener/blob/main/Backend/package.json"

    classDef frontend fill:#E8F0FE,stroke:#0F4C81;
    classDef backend fill:#FEF3C7,stroke:#927A00;
    classDef db fill:#D1FAE5,stroke:#064E3B;
```
