# tanmandal/short-url architecture

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

- Interactive diagram: https://gitdiagram.com/tanmandal/short-url
- Repository: https://github.com/tanmandal/short-url

## Overview

##### What this project is (type + purpose)

This repo is a **single-service backend API**: a **FastAPI-based URL shortener + management service** with **JWT/Bearer-token authentication**.

From the README + file tree, the system is essentially one deployable “container” (the FastAPI app) that exposes:
- **Public** endpoints (create short URL, login, redirect, health)
- **Protected** endpoints (pause/resume/delete/change/reset/details + token validate/refresh)

There is **no explicit DB layer** shown in the tree (no `db.py`, no migrations, no ORM config). So the “storage” is most likely:
- an **in-memory dictionary** inside the process, or
- a lightweight file-based store,

##### How to read the file structure (map files → architectural components)

Top-level modules strongly imply a classic “routes + models + utilities” layout:

- `main.py`
- The **entrypoint**: creates `app = FastAPI()`
- Defines **HTTP endpoints** listed in README
- Orchestrates calls into helpers/auth/model validation
- `models.py`
- **Pydantic schemas** (e.g., `URLEntry`, `LoginEntry`, `ResetEntry`)
- Possibly internal “URL record” structure (paused flag, hit count)
- `auth_utils.py`
- **JWT creation/verification**, token expiry, refresh/validate logic
- FastAPI security dependency (HTTP Bearer)
- `helper.py`
- URL code validation, password hashing/verification, hit counter updates
- Storage CRUD helpers (create/update/delete/find)
- `requirements.txt`
- Confirms the **runtime stack**: FastAPI, Pydantic, JWT libs, etc.

Actors and external dependencies:
- API Consumer (Browser/User/Client app, curl, Postman)
- FastAPI URL Shortener API (this system)
- (Optional) External Destination Websites (for redirects)
- (Optional) Observability/Monitoring (only if present; README only has `/health`)

- **One container/process**: `Uvicorn + FastAPI app`
- **Storage**: “In-memory store” (or “local file store”) if that’s what code shows
- No separate frontend, no worker queue, no cache (unless discovered in code)

Inside the FastAPI container, break it down into:
- **Route Handlers / Controllers** (in `main.py`)
- Public routes: `/create`, `/login`, `/{url_code}`, `/health`, `/`
- Protected routes: `/pause`, `/resume`, `/delete`, `/change_url`, `/reset_hits`, `/details`, `/change_password`, `/validate_token`, `/refresh_token`
- **Auth Component** (`auth_utils.py`)
- Token issuance (login)
- Token validation dependency (Bearer)
- Token refresh/validate endpoints
- **Domain/Service Component** (`helper.py`)
- URL CRUD (create/update/delete)
- Status transitions (pause/resume)
- Counter mutation (increment hits, reset hits)
- Password change logic
- **Schemas/Contracts** (`models.py`)
- Request/response models
- **Data Store**
- “URL Repository” abstraction (even if it’s just a dict)
- Data model fields: `url_code`, `url`, `url_pass` (hashed?), `paused`, `hits`, created_at, etc. (whatever exists in code)

##### Create
- Client → `POST /create` (FastAPI route in `main.py`)
- Route validates request via `models.py`
- Route calls `helper.py` to store new URL record (and password hash)
- Response returns short URL

##### Login → Token
- Client → `POST /login`
- Route calls `helper.py` (lookup url_code + verify password)
- If valid: route calls `auth_utils.py` to mint JWT access token (and maybe refresh token)
- Return token to client

##### Protected management operations
- Client includes `Authorization: Bearer <token>`
- FastAPI dependency (in `auth_utils.py`) validates token
- Route handler calls `helper.py` to mutate URL record (pause/resume/delete/change/reset/details)

##### Redirect
- Client → `GET /{url_code}`
- Route calls `helper.py` to resolve record
- If paused/not found → error
- Else increment hits + return RedirectResponse to destination URL

##### Token validate/refresh
- Client → `/validate_token` uses `auth_utils.py` verify path
- Client → `/refresh_token` uses refresh logic in `auth_utils.py`

- URL state: **Active ↔ Paused**
- Counters: `hits++` on redirect, `hits=0` on reset
- Credential state: password set at create, verified on login, updated on change_password
- URL destination changes on `/change_url`

##### Architectural patterns to highlight (specific to this repo)

- **Monolithic API service**: everything in one FastAPI app.
- **Route-layer orchestration**: `main.py` as the controller layer.
- **Utility/service split**: `helper.py` and `auth_utils.py` concentrate business logic.
- **Schema-first validation**: Pydantic models in `models.py` define the API contract.
- **Token-based auth**: Bearer token required for management endpoints; login tied to `url_code` + password.

##### Enumerate endpoints from `main.py` and group them
- Public: create/login/redirect/health
- Protected: management + token ops
##### For each endpoint, identify
- Which **Pydantic model** it consumes/returns (`models.py`)
- Which **auth dependency** it uses (`auth_utils.py`)
- Which **helper functions** it calls (`helper.py`)
- Which **data structure** it reads/writes (search for a global dict/list/JSON file)
- “Redirect Controller”, “URL Management Controller”, “Auth Controller”
- “JWT Auth Service”, “URL Service”, “URL Repository”
- “In-memory (process local)” or “File-based” depending on code
- Mention implications: not shared across instances, resets on restart (if applicable)

- Create + Login (token issuance)
- Redirect (lookup + paused check + hit increment + redirect)
- Protected operation (Bearer validation → business operation → response)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Context / Actors
  %% =========================
  subgraph "Context"
    Client["API Consumer (Browser / App / curl)"]:::external
    Dest["Destination Website(s)"]:::external
  end

  %% =========================
  %% Container (Single deployable)
  %% =========================
  subgraph "Container: FastAPI URL Shortener API (Single Service)"
    direction TB

    Edge["Uvicorn + FastAPI App"]:::container

    subgraph "HTTP Layer (Routes/Controllers) - main.py"
      direction TB
      Public["Public Endpoints\n- POST /create\n- POST /login\n- GET /{url_code}\n- GET /health\n- GET /"]:::http
      Protected["Protected Endpoints (Bearer JWT)\n- POST /pause /resume /delete\n- POST /change_url /reset_hits\n- GET /details\n- POST /change_password\n- GET /validate_token\n- POST /refresh_token"]:::http
    end

    subgraph "Components"
      direction TB
      Auth["Auth Component (JWT + Bearer dependency)\n- issue_token\n- verify_token\n- refresh/validate"]:::auth
      Domain["Domain/Service Component\n(URL CRUD + state + counters + password)\n- create/update/delete\n- pause/resume\n- redirect resolve + hits++\n- reset hits\n- change url/password"]:::domain
      Schemas["Schemas / Contracts (Pydantic Models)\nURLEntry / LoginEntry / ResetEntry / ..."]:::schema
      Repo[("URL Store / Repository\n(Internal; likely in-memory dict\nor lightweight file store)\nLimit: process-local, resets on restart")]:::datastore
      FutureDB[("Future DB (Optional)\nPostgreSQL / Redis / etc.")]:::datastoreFuture
    end

    Docs["API Docs / Usage (README)"]:::docs
    Deps["Runtime Dependencies (requirements.txt)\nFastAPI, Pydantic, JWT libs, ..."]:::deps
  end

  %% =========================
  %% Primary request flows (vertical)
  %% =========================
  Client -->|"HTTP requests"| Edge
  Edge -->|"routes"| Public
  Edge -->|"routes"| Protected

  %% Validation via schemas
  Public -->|"request_validation"| Schemas
  Protected -->|"request_validation"| Schemas

  %% Public flows
  Public -->|"POST /create -> create_short_url()"| Domain
  Public -->|"POST /login -> verify_password()"| Domain
  Public -->|"POST /login -> mint_JWT()"| Auth
  Public -->|"GET /{url_code} -> resolve + paused_check + hits++"| Domain

  %% Protected flows (Bearer auth gate)
  Protected -->|"Bearer_dependency: validate_JWT"| Auth
  Protected -->|"on_success: mutate/read URL record"| Domain

  %% Domain -> storage
  Domain -->|"CRUD + state_transitions"| Repo

  %% Optional future persistence
  Repo -.->|"optional_persistence"| FutureDB

  %% Redirect out to destination websites
  Domain -->|"RedirectResponse (Location: target URL)"| Dest

  %% Documentation & dependencies relationships
  Docs -.->|"describes_endpoints"| Public
  Docs -.->|"describes_endpoints"| Protected
  Deps -.->|"provides_runtime_stack"| Edge

  %% =========================
  %% Notes (state transitions)
  %% =========================
  NoteState["State & Data Transitions\n- Active <-> Paused\n- hits++ on redirect\n- hits=0 on reset\n- password set on create, verified on login, updated on change_password\n- destination URL updated on change_url"]:::note
  Domain -.->|"enforces"| NoteState

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click Edge "https://github.com/tanmandal/short-url/blob/main/main.py"
  click Public "https://github.com/tanmandal/short-url/blob/main/main.py"
  click Protected "https://github.com/tanmandal/short-url/blob/main/main.py"
  click Auth "https://github.com/tanmandal/short-url/blob/main/auth_utils.py"
  click Domain "https://github.com/tanmandal/short-url/blob/main/helper.py"
  click Schemas "https://github.com/tanmandal/short-url/blob/main/models.py"
  click Deps "https://github.com/tanmandal/short-url/blob/main/requirements.txt"
  click Docs "https://github.com/tanmandal/short-url/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ECEFF1,stroke:#607D8B,color:#263238,stroke-width:1px
  classDef container fill:#E3F2FD,stroke:#1565C0,color:#0D47A1,stroke-width:2px
  classDef http fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1,stroke-width:1.5px
  classDef auth fill:#EDE7F6,stroke:#6A1B9A,color:#4A148C,stroke-width:1.5px
  classDef domain fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20,stroke-width:1.5px
  classDef schema fill:#FFF3E0,stroke:#EF6C00,color:#E65100,stroke-width:1.5px
  classDef datastore fill:#FFE0B2,stroke:#EF6C00,color:#E65100,stroke-width:2px
  classDef datastoreFuture fill:#FFF8E1,stroke:#F9A825,color:#6D4C41,stroke-width:2px,stroke-dasharray: 6 4
  classDef docs fill:#F3E5F5,stroke:#8E24AA,color:#4A148C,stroke-width:1.5px
  classDef deps fill:#FAFAFA,stroke:#616161,color:#212121,stroke-width:1.5px
  classDef note fill:#FFFDE7,stroke:#FBC02D,color:#5D4037,stroke-width:1px,stroke-dasharray: 4 3
```
