{"id":44812554,"url":"https://github.com/recursivezero/tiny","last_synced_at":"2026-02-16T17:01:56.164Z","repository":{"id":329414746,"uuid":"1118225534","full_name":"recursivezero/tiny","owner":"recursivezero","description":"URL Shortner project","archived":false,"fork":false,"pushed_at":"2026-02-13T19:51:43.000Z","size":8135,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-13T20:34:11.022Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/recursivezero.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-17T12:48:45.000Z","updated_at":"2026-02-13T17:27:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/recursivezero/tiny","commit_stats":null,"previous_names":["recursivezero/tiny"],"tags_count":0,"template":false,"template_full_name":"recursivezero/template","purl":"pkg:github/recursivezero/tiny","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivezero%2Ftiny","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivezero%2Ftiny/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivezero%2Ftiny/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivezero%2Ftiny/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/recursivezero","download_url":"https://codeload.github.com/recursivezero/tiny/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivezero%2Ftiny/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29513426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T09:05:14.864Z","status":"ssl_error","status_checked_at":"2026-02-16T08:55:59.364Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-16T17:00:30.564Z","updated_at":"2026-02-16T17:01:56.158Z","avatar_url":"https://github.com/recursivezero.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tiny URL Generator\r\n\r\n\u003e A modern, Bitly-style tiny URL web application built with FastAPI, optional MongoDB, and a sleek web UI.\r\n\r\n![Python](https://img.shields.io/badge/Python-3.11-blue.svg)\r\n![FastAPI](https://img.shields.io/badge/FastAPI-Backend-teal.svg)\r\n![MongoDB](\u003chttps://img.shields.io/badge/Database-MongoDB%20(Optional)-green.svg\u003e)\r\n![License](https://img.shields.io/badge/License-MIT-yellow.svg)\r\n![Status](https://img.shields.io/badge/Status-Active-success.svg)\r\n\r\n---\r\n\r\n## Overview\r\n\r\nTiny URL is a sleek, fast, and modern URL shortening platform built using FastAPI with optional MongoDB persistence.\r\nIt converts long URLs into short, shareable links — just like Bitly.\r\n\r\nThe project supports:\r\n\r\n- Web UI (FastAPI + Jinja templates)\r\n- REST API (FastAPI)\r\n- Offline Mode (No MongoDB required)\r\n\r\nThis project is designed with:\r\n\r\n- Clean startup lifecycle (no racing configs)\r\n- Optional database dependency\r\n- Graceful degradation when MongoDB is unavailable\r\n- In-memory cache fallback\r\n- QR code generation with auto folder creation\r\n\r\n---\r\n\r\n## Features\r\n\r\n### User Features\r\n\r\n- Convert long URLs into short, unique codes\r\n- Default checkbox QR code generation\r\n- Clean Bitly-style result card\r\n- Copy \u0026 share buttons\r\n- Download URL button\r\n- URL validation and sanitization\r\n- Fully responsive UI\r\n- Recent URLs page (when DB is available)\r\n- Visit count tracking (when DB is available)\r\n- QR image auto-generation with logo\r\n- Cache-accelerated redirects\r\n\r\n### API \u0026 Developer Features\r\n\r\n- REST API for URL shortening\r\n- API version endpoint\r\n- Swagger / OpenAPI documentation\r\n- API landing page\r\n- Cache layer for fast redirects\r\n- Graceful offline mode (no DB required)\r\n- Clean startup lifecycle using FastAPI lifespan\r\n- Optional MongoDB dependency\r\n\r\n---\r\n\r\n## Short Code Generation Algorithm\r\n\r\nThe app uses a Random Alphanumeric Short Code Generator.\r\n\r\n### Algorithm Details\r\n\r\n- Uses `string.ascii_letters + string.digits`\r\n- Randomly picks characters\r\n- Generates a 6-character short ID\r\n- Checks MongoDB for collisions (if DB is enabled)\r\n- Automatically regenerates on collision\r\n\r\n### Example\r\n\r\n```python\r\nimport random, string\r\n\r\ndef generate_code(length=6):\r\n    chars = string.ascii_letters + string.digits\r\n    return ''.join(random.choice(chars) for _ in range(length))\r\n```\r\n\r\n---\r\n\r\n## Tech Stack\r\n\r\n| Layer       | Technology              |\r\n| ----------- | ----------------------- |\r\n| UI Backend  | FastAPI                 |\r\n| API Backend | FastAPI                 |\r\n| Database    | MongoDB (Optional)      |\r\n| Cache       | In-Memory (Python dict) |\r\n| Frontend    | HTML, CSS, Vanilla JS   |\r\n| QR Code     | qrcode + Pillow         |\r\n| API Server  | Uvicorn                 |\r\n| Validation  | Pydantic v2             |\r\n| Env Mgmt    | python-dotenv           |\r\n| Tooling     | Poetry                  |\r\n\r\n---\r\n\r\n[Project Tree](./docs/tree.md)\r\n\r\n## ⚙️ How to Run the Project Locally\r\n\r\n`Virtual Environment Configuration`\r\n\r\n```bash\r\npoetry config virtualenvs.path /your/desired/path\r\n```\r\n\r\n## Environment Configuration\r\n\r\nEnsure below files are configured (create if not exist) properly to run the project;\r\n\r\nSupported env files:\r\n\r\n- .env.development\r\n- .env.local\r\n- .env (production)\r\n\r\n```text\r\nENV=development\r\nDOMAIN=http://127.0.0.1:8000\r\nMONGO_URI=mongodb://\u003cuser\u003e:\u003cpassword\u003e@localhost:27017/tiny_url?authSource=tiny_url\r\nDATABASE_NAME=tiny_url\r\n```\r\n\r\n## Install Dependencies\r\n\r\n```bash\r\npoetry lock --no-cache --regenerate\r\npoetry install  --all-extras --with dev\r\n```\r\n\r\nOr manually\r\n\r\n```bash\r\npoetry install\r\n```\r\n\r\n## How to Run\r\n\r\n```bash\r\npoetry run tiny dev\r\n```\r\n\r\nAccess: \u003chttp://127.0.0.1:8000\u003e\r\n\r\n## Run FastAPI Server\r\n\r\n```bash\r\npoetry run tiny api\r\n```\r\n\r\nAccess: \u003chttp://127.0.0.1:8001\u003e\r\n\r\n## Offline Mode (No Database)\r\n\r\nTinyURL supports graceful offline mode.\r\n\r\n### What works\r\n\r\n- App starts normally\r\n- UI loads\r\n- Short URLs are generated\r\n- QR codes are generated\r\n- Redirects work from in-memory cache\r\n\r\n### What is disabled\r\n\r\n- Recent URLs page\r\n- Persistent redirects after restart\r\n- Visit count tracking\r\n\r\nOffline Mode activates automatically when:\r\n\r\n- MongoDB is down\r\n- OR pymongo is not installed\r\n- OR MONGO_URI is missing/invalid\r\n\r\nLog message:\r\n\r\n```\r\n⚠️ MongoDB connection failed. Running in NO-DB mode.\r\n```\r\n\r\n---\r\n\r\n## Switching Modes\r\n\r\n### Without MongoDB\r\n\r\n```sh\r\nsudo systemctl stop mongod\r\npoetry run tiny dev\r\n```\r\n\r\nor\r\n\r\n```sh\r\npoetry run pip uninstall pymongo\r\npoetry run tiny dev\r\n```\r\n\r\n---\r\n\r\n## Troubleshooting\r\n\r\nsometimes there might be chances that virtual environment get corrupted then delete the old virtual environment and start afresh.\r\n\r\n```sh\r\npoetry env info\r\n# this will provide virtual environment name\r\npoetry env remove \u003cenvironment-full-name\u003e\r\n```\r\n\r\n### Mongo auth error\r\n\r\nEncode special chars:\r\n\r\n@ ? %40\r\n\r\nExample:\r\n\r\n```\r\nMONGO_URI=mongodb://user%40gmail.com:Pass%40123@localhost:27017/tiny_url?authSource=tiny_url\r\n```\r\n\r\n---\r\n\r\n## WSL Notes\r\n\r\n```sh\r\nsudo systemctl start mongod\r\npoetry run tiny dev\r\n```\r\n\r\n## Build \u0026 Packaging\r\n\r\n## Build Package\r\n\r\n```bash\r\npoetry clean\r\npoetry build\r\n```\r\n\r\nArtifacts in `dist/`\r\n\r\n- tiny-x.y.0-py3-none-any.whl\r\n- tiny-x.y.0.tar.gz\r\n\r\n## Test Locally\r\n\r\n```bash\r\npython -m venv .venv-dist\r\nsource .venv-dist/bin/activate\r\n# Windows\r\n.venv-dist\\Scripts\\activate\r\n```\r\n\r\n### Install package\r\n\r\n```bash\r\npip install dist/*.whl\r\npip install --upgrade dist/*.whl\r\n```\r\n\r\n## License\r\n\r\n📜Docs\r\n[run_with_curl](docs/run_with_curl)\r\n\r\nScreenshots:\r\nHome Page:\r\n![home page](assets/images/home.png)\r\n![home dark mode](assets/images/home_dark.png)\r\n![home page](assets/images/valid.png)\r\n![home layout](assets/images/short_url.png)\r\n![recent](assets/images/recent.png)\r\ntiny API Page:\r\n![API](assets/images/API_page.png)\r\n![API1](assets/images/api_page2.png)\r\nNo DB Mode:\r\n![NO DB](assets/images/no-db.png)\r\n📜License\r\n\r\n[MIT](LICENSE)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecursivezero%2Ftiny","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecursivezero%2Ftiny","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecursivezero%2Ftiny/lists"}