How qkeluna/talisik-short-url works
Project Type & Purpose
• This is a monorepo for a multi‐platform URL shortener.
• Core business logic in Python (talisik/ Python library).
• REST API service built with FastAPI (api/ directory).
• JavaScript/TypeScript client SDK as an npm package (packages/talisik-client/).
• CLI demo (cli_demo.py) and usage examples (examples/).
• It’s designed to be used as a Python library, a hosted API, a JS/React/Vue/etc. SDK, or a CLI tool.
File‐Structure Analysis & Architectural Insights
• Top‐level directories:
• talisik/ – Python domain logic (URL shortening, storage, config, models).
• api/ – FastAPI application exposing REST endpoints.
• packages/talisik-client/ – Rollup‐built npm package for JS clients.
• examples/ – Demo projects showing React, Node.js usage.
• docs/ – Integration and deployment guides.
• tests/ & various test_*.py – Unit/integration tests.
• Config & Deployment:
• Makefile, Procfile, docker‐ready scripts.
• pyproject.toml, setup.py, package.json for packaging.
• Patterns & Layers:
• Layered architecture: Client Layer → API Layer → Business Logic (Core Library) → Storage/Persistence.
• Clear “ports & adapters” approach: core logic is decoupled from HTTP and DB.
Key Components
A. Client SDKs & CLI
• JS/TS SDK (TalisikClient via npm).
• Python library import (URLShortener).
• CLI demo (cli_demo.py).
B. API Service
• FastAPI app (api/main.py, wsgi.py).
• Uvicorn/Gunicorn (deployment container).
C. Core Library
• Domain models & logic (talisik/core/*).
• Configuration (config.py), shortener logic, storage adapter.
D. Data Persistence
• Underlying storage (file system, in‐memory, or optional Xata integration).
E. External Systems
• Optional analytics/CDN, custom domains, third‐party DBs or caching.
Relationships & Data Flows
• JS Client → HTTP POST/GET → FastAPI → invokes → Core Library → reads/writes → Storage → returns → FastAPI → HTTP response → JS Client.
• Python Consumer imports → Core Library → interacts directly with → Storage (bypass API).
• CLI imports → Core Library → prints output to STDOUT.
• Examples layer sits atop the JS SDK or direct HTTP calls to the API.
Architectural Patterns & Tech Stack
• Hexagonal / Ports‐and‐Adapters: Core library is independent of HTTP or DB.
• Layered / Clean Architecture:
• Presentation (SDK, API)
• Application (shortener use‐cases)
• Domain (models, rules)
• Infrastructure (storage adapters, HTTP framework)
• Technologies:
• Python 3 + FastAPI + Uvicorn/Gunicorn
• Node.js + Rollup + TypeScript for npm client
• Docker, Makefile for orchestration