# qkeluna/talisik-short-url architecture

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

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

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Clients / SDKs" 
        direction TB
        JS["TalisikClient (npm)"]:::frontend
        PyLib["URLShortener Python Library"]:::frontend
        CLI["CLI Demo"]:::frontend
        Examples["Usage Examples"]:::frontend
    end

    %% API Layer
    subgraph "API Service" 
        direction TB
        API["FastAPI REST API"]:::api
    end

    %% Core Library
    subgraph "Core Library" 
        direction TB
        Core["URLShortener Core Library"]:::core
    end

    %% Storage / Persistence
    subgraph "Storage / Persistence" 
        direction TB
        Storage["Storage Adapter / DB"]:::storage
    end

    %% External (optional)
    subgraph "Optional Integrations" 
        direction TB
        Analytics["Analytics / CDN"]:::external
        ThirdPartyDB["Third-Party DB / Cache"]:::external
    end

    %% Data Flows
    JS -->|HTTP/JSON| API
    API -->|"invokes"| Core
    Core -->|"reads/writes"| Storage
    Storage -->|"response"| Core
    Core -->|"returns JSON"| API
    API -->|HTTP/JSON| JS

    PyLib -->|"Python call"| Core
    CLI -->|"Python call"| Core
    Examples -->|uses SDK| JS
    Examples -->|direct HTTP| API

    Core -->|"optional"| Analytics
    Core -->|"optional"| ThirdPartyDB

    %% Click Events
    click JS "https://github.com/qkeluna/talisik-short-url/tree/main/packages/talisik-client/"
    click PyLib "https://github.com/qkeluna/talisik-short-url/tree/main/talisik/core/"
    click API "https://github.com/qkeluna/talisik-short-url/tree/main/api/"
    click CLI "https://github.com/qkeluna/talisik-short-url/blob/main/cli_demo.py"
    click Examples "https://github.com/qkeluna/talisik-short-url/tree/main/examples/"

    %% Styles
    classDef frontend fill:#D6E9F8,stroke:#5DADE2,color:#154360,stroke-width:1px;
    classDef api fill:#D1F2EB,stroke:#1ABC9C,color:#0E6251,stroke-width:1px;
    classDef core fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:1px;
    classDef storage fill:#FDEBD0,stroke:#EB984E,color:#873600,stroke-width:1px;
    classDef external fill:#F4F6F6,stroke-dasharray: 5 5,stroke:#7B7D7D,color:#616A6B,stroke-width:1px;
```
