# yashz0r0/url-shortener-service architecture

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

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

## Overview

1. **Repository shape**
   - This is a backend-only **URL shortener service** implemented as a Node.js application.
   - The code is organized into a classic HTTP API layering: **server bootstrap → routes → middleware/controllers → models → database**.

2. **Application entry point**
   - `server.js` is the runtime entrypoint. It likely creates the app, wires middleware, mounts routes, loads DB config, and starts listening on a port.
   - `package.json` / `package-lock.json` indicate the project is dependency-managed with npm.

3. **Routing boundary**
   - `routes/` splits the HTTP surface into three route groups:
     - `routes/auth.js` for authentication-related endpoints
     - `routes/urls.js` for short URL creation and lookup/redirect behavior
     - `routes/index.js` for root-level or miscellaneous endpoints
   - This is the primary API boundary visible from outside the service.

4. **Authentication subsystem**
   - `controllers/authController.js` handles auth business logic.
   - `models/user.js` represents user persistence.
   - `middleware/auth.js` is the access-control boundary, likely enforcing that some URL operations require an authenticated user.
   - The architecture implies a user-account layer separate from the URL-shortening layer.

5. **URL management subsystem**
   - `controllers/urlController.js` owns URL shortening logic and URL-related request handling.
   - `models/url.js` stores the persisted mapping between a long destination URL and its shortened form.
   - This subsystem is where the service’s core value is implemented: create, resolve, and manage shortened links.

6. **Controller-to-model flow**
   - Requests come in through routes, then controllers translate them into model operations.
   - The `models/` layer is the persistence abstraction, keeping storage concerns separated from HTTP concerns.
   - `config/db.js` centralizes database connection setup, which suggests a single shared datastore for users and URLs.

7. **Data and trust boundaries**
   - The service separates **public request handling** from **authenticated operations**.
   - The auth middleware is the main trust boundary: unauthenticated requests can reach public endpoints, while protected endpoints are filtered before controllers run.
   - User identity likely influences which URL records can be created or managed.

8. **Likely request flows**
   - **Auth flow:** client → auth routes → auth controller → user model → database.
   - **Shorten flow:** client → URL routes → auth middleware (if protected) → URL controller → URL model → database.
   - **Resolve/redirect flow:** client hits shortened URL → URL routes/controller → URL model lookup → redirect or response.

9. **Persistence layer**
   - The presence of dedicated `user` and `url` models indicates two core entities:
     - users/accounts
     - shortened URL records
   - `config/db.js` is the only explicit infrastructure module, so the external dependency is primarily the backing database.

10. **Architecture summary for diagramming**
    - Draw the service as a single Node.js API process with:
      - an HTTP ingress layer (`routes/`)
      - an auth gate (`middleware/auth.js`)
      - two business domains (`authController` + `urlController`)
      - two persisted entities (`User`, `Url`)
      - one shared database connection (`config/db.js`)
    - There is no evidence of a frontend, job queue, or separate microservices in this repo.

Main entry points: [`server.js`](https://github.com/yashz0r0/url-shortener-service/blob/main/server.js) (server.js), [`routes/urls.js`](https://github.com/yashz0r0/url-shortener-service/blob/main/routes/urls.js) (URL routes), [`middleware/auth.js`](https://github.com/yashz0r0/url-shortener-service/blob/main/middleware/auth.js) (Auth guard), [`controllers/urlController.js`](https://github.com/yashz0r0/url-shortener-service/blob/main/controllers/urlController.js) (URL controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Runtime"]
  node_server_js["server.js<br/>entrypoint<br/>[server.js]"]
  node_package_json["npm<br/>dependency manifest<br/>[package.json]"]
end

subgraph group_g_http["HTTP API"]
  node_routes_index["Root routes<br/>route set<br/>[index.js]"]
  node_routes_auth["Auth routes<br/>route set<br/>[auth.js]"]
  node_routes_urls["URL routes<br/>route set<br/>[urls.js]"]
  node_auth_mw{{"Auth guard<br/>middleware<br/>[auth.js]"}}
end

subgraph group_g_domain["Domain"]
  node_auth_controller["Auth controller<br/>[authController.js]"]
  node_url_controller["URL controller<br/>[urlController.js]"]
end

subgraph group_g_data["Persistence"]
  node_user_model[("User model<br/>[user.js]")]
  node_url_model[("URL model<br/>[url.js]")]
  node_db_config(("DB config<br/>infrastructure<br/>[db.js]"))
end

node_package_json -.->|"runs"| node_server_js
node_server_js -->|"mounts"| node_routes_index
node_server_js -->|"mounts"| node_routes_auth
node_server_js -->|"mounts"| node_routes_urls
node_server_js -->|"uses"| node_auth_mw
node_server_js -->|"connects"| node_db_config
node_routes_auth -->|"dispatches to"| node_auth_controller
node_routes_urls -->|"protects with"| node_auth_mw
node_routes_urls -->|"dispatches to"| node_url_controller
node_routes_index -.->|"may reach"| node_url_controller
node_auth_controller -->|"reads/writes"| node_user_model
node_url_controller -->|"reads/writes"| node_url_model
node_user_model -->|"uses"| node_db_config
node_url_model -->|"uses"| node_db_config
node_auth_mw -.->|"verifies"| node_user_model

click node_server_js "https://github.com/yashz0r0/url-shortener-service/blob/main/server.js"
click node_package_json "https://github.com/yashz0r0/url-shortener-service/blob/main/package.json"
click node_routes_index "https://github.com/yashz0r0/url-shortener-service/blob/main/routes/index.js"
click node_routes_auth "https://github.com/yashz0r0/url-shortener-service/blob/main/routes/auth.js"
click node_routes_urls "https://github.com/yashz0r0/url-shortener-service/blob/main/routes/urls.js"
click node_auth_mw "https://github.com/yashz0r0/url-shortener-service/blob/main/middleware/auth.js"
click node_auth_controller "https://github.com/yashz0r0/url-shortener-service/blob/main/controllers/authController.js"
click node_url_controller "https://github.com/yashz0r0/url-shortener-service/blob/main/controllers/urlController.js"
click node_user_model "https://github.com/yashz0r0/url-shortener-service/blob/main/models/user.js"
click node_url_model "https://github.com/yashz0r0/url-shortener-service/blob/main/models/url.js"
click node_db_config "https://github.com/yashz0r0/url-shortener-service/blob/main/config/db.js"

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_server_js,node_package_json toneBlue
class node_routes_index,node_routes_auth,node_routes_urls,node_auth_mw toneAmber
class node_auth_controller,node_url_controller toneMint
class node_user_model,node_url_model,node_db_config toneRose
```

## Components

### Runtime

Process entrypoint and package-managed Node.js runtime

- [server.js](https://github.com/yashz0r0/url-shortener-service/blob/main/server.js): entrypoint · Bootstraps the app, wiring middleware, routes, database, and listen loop · `server.js`
- [npm](https://github.com/yashz0r0/url-shortener-service/blob/main/package.json): dependency manifest · Node package metadata and dependency management · `package.json`

### HTTP API

Routes and request-handling boundaries

- [Root routes](https://github.com/yashz0r0/url-shortener-service/blob/main/routes/index.js): route set · Top-level or miscellaneous HTTP endpoints · `routes/index.js`
- [Auth routes](https://github.com/yashz0r0/url-shortener-service/blob/main/routes/auth.js): route set · Authentication-related HTTP endpoints · `routes/auth.js`
- [URL routes](https://github.com/yashz0r0/url-shortener-service/blob/main/routes/urls.js): route set · Short URL creation, lookup, and redirect endpoints · `routes/urls.js`
- [Auth guard](https://github.com/yashz0r0/url-shortener-service/blob/main/middleware/auth.js): middleware · Access-control gate for protected requests · `middleware/auth.js`

### Domain

Auth and URL business logic

- [Auth controller](https://github.com/yashz0r0/url-shortener-service/blob/main/controllers/authController.js): controller · Handles authentication and user-facing auth flows · `controllers/authController.js`
- [URL controller](https://github.com/yashz0r0/url-shortener-service/blob/main/controllers/urlController.js): controller · Implements shortening, lookup, and redirect behavior · `controllers/urlController.js`

### Persistence

Models and shared database connection

- [User model](https://github.com/yashz0r0/url-shortener-service/blob/main/models/user.js): model · Persistence abstraction for user accounts · `models/user.js`
- [URL model](https://github.com/yashz0r0/url-shortener-service/blob/main/models/url.js): model · Persistence abstraction for shortened URL records · `models/url.js`
- [DB config](https://github.com/yashz0r0/url-shortener-service/blob/main/config/db.js): infrastructure · Shared database connection setup · `config/db.js`

## Connections

- npm → server.js: runs · npm-managed application entrypoint
- server.js → Root routes: mounts · Registers root endpoints
- server.js → Auth routes: mounts · Registers authentication endpoints
- server.js → URL routes: mounts · Registers URL endpoints
- server.js → Auth guard: uses · Applies request authentication gate
- server.js → DB config: connects · Initializes shared database connection
- Auth routes → Auth controller: dispatches to · Routes auth requests into controller logic
- URL routes → Auth guard: protects with · Applies access control before protected URL actions
- URL routes → URL controller: dispatches to · Routes URL requests into controller logic
- Root routes → URL controller: may reach · Root endpoints may expose redirect or landing behavior
- Auth controller → User model: reads/writes · Creates and authenticates users through persistence
- URL controller → URL model: reads/writes · Creates and resolves shortened URL records
- User model → DB config: uses · Shares the central database connection
- URL model → DB config: uses · Shares the central database connection
- Auth guard → User model: verifies · Likely checks user identity or session state