How tanmandal/short-url works
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)