# veenzent/scissor_url architecture

> Architecture diagram of the GitHub repository veenzent/scissor_url, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/veenzent/scissor_url
- Repository: https://github.com/veenzent/scissor_url

## Overview

##### Project type and purpose
- This is a full-stack URL-shortener service (“Scissor API”)
- Frontend: static HTML/CSS/JS under `frontend/`
- Backend: Python FastAPI app in `main.py` + `scissorapp/` package
- Persistence: relational database (configured via `scissorapp/instance/config.py`)
- Auxiliary functionality: rate-limiting (`scissorapp/rate_limiter.py`), dependency injection, OpenAPI docs

##### File structure
- Top-level
- `frontend/` – static site assets and `scissor.js` (calls the API)
- `main.py` – entry point, mounts routers and static files
- `requirements.txt` – external libraries (e.g. FastAPI, SQLAlchemy, an async driver)
- `scissorapp/`
– `routers/link_shortener.py` – API endpoints
– `models.py` – ORM model(s) for URL mappings
– `schemas.py` – Pydantic request/response models
– `database.py` – DB session / engine setup
– `dependencies.py` – DI helpers (get_db, get_rate_limiter, etc.)
– `rate_limiter.py` – rate-limit logic
– `instance/config.py` – environment-specific settings (DB URL, secrets)
- Test harness in `test_main.py`

##### README
- Confirms FastAPI (“docs” at `/docs`)
- Purpose: expose a simple URL-shortening REST API
- Deployment hint: runs on Render.com

##### Diagramming conventions
- Labels: Use component names (`Frontend UI`, `FastAPI Router`, `DB Session Factory`, `PostgreSQL`)
- Solid → request/response flow
- Green for API server components

##### Detailed capture
- `main.py` bootstrapping: mounting static files + routers
- How `dependencies.py` ties together DB and rate limiter per request
- `routers/link_shortener.py` endpoints (`POST /shorten`, `GET /{id}`)
- OpenAPI docs endpoint (`/docs`) as a subcomponent of the API server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client (Browser/HTTP Client)"]:::client

    %% Frontend UI
    subgraph "Frontend Static Site" 
        direction TB
        Index["index.html"]:::ui
        JS["scissor.js"]:::ui
        Style1["style.css"]:::ui
        Style2["general-styles.css"]:::ui
        Assets["assets/"]:::ui
    end

    %% API Server
    subgraph "FastAPI App" 
        direction TB
        Main["main.py"]:::server
        Router["Link Shortener Router\n(POST /shorten, GET /{id})"]:::server
        DI["Dependency Injection Helpers"]:::server
        DBSetup["DB Session & Engine Setup"]:::server
        Models["ORM Models (URL Mapping)"]:::server
        Schemas["Pydantic Schemas"]:::server
        RateLimiter["Rate Limiter Module"]:::ratelimiter
        Config["Environment Config"]:::server
        Docs["OpenAPI Docs (/docs)"]:::server
    end

    %% Database
    Database["Relational Database\n(PostgreSQL/SQLite)"]:::database

    %% Test & Dependencies
    Requirements["requirements.txt"]:::config
    Tests["test_main.py"]:::config

    %% Flows
    Client -->|"loads index.html"| Index
    Client -->|"loads assets & CSS/JS"| JS
    Client -->|"loads CSS"| Style1
    Client --> Style2
    Client --> Assets

    Client -->|"calls API"| Router
    Client -->|"views docs"| Docs

    Index -->|"served by main.py"| Main
    JS -->|"fetch POST/GET"| Router

    Main -->|"mounts router"| Router
    Main -->|"mounts static files"| Index

    Router -->|"inject get_db, get_rate_limiter"| DI
    DI -->|"provides DB session"| DBSetup
    DI -->|"provides rate limiter"| RateLimiter

    Router -->|"uses ORM models"| Models
    Router -->|"validates with schemas"| Schemas

    DBSetup -->|"connects to"| Database
    Config -.-> Main
    Requirements -.-> Main
    Tests -.-> Main

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000
    classDef ui fill:#ADD8E6,stroke:#000
    classDef server fill:#98FB98,stroke:#000
    classDef database fill:#FFA500,stroke:#000
    classDef ratelimiter fill:#D8BFD8,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000

    %% Click Events
    click Index "https://github.com/veenzent/scissor_url/blob/master/frontend/index.html"
    click JS "https://github.com/veenzent/scissor_url/blob/master/frontend/scissor.js"
    click Style1 "https://github.com/veenzent/scissor_url/blob/master/frontend/style.css"
    click Style2 "https://github.com/veenzent/scissor_url/blob/master/frontend/general-styles.css"
    click Assets "https://github.com/veenzent/scissor_url/tree/master/frontend/assets/"
    click Main "https://github.com/veenzent/scissor_url/blob/master/main.py"
    click Router "https://github.com/veenzent/scissor_url/blob/master/scissorapp/routers/link_shortener.py"
    click DI "https://github.com/veenzent/scissor_url/blob/master/scissorapp/dependencies.py"
    click DBSetup "https://github.com/veenzent/scissor_url/blob/master/scissorapp/database.py"
    click Models "https://github.com/veenzent/scissor_url/blob/master/scissorapp/models.py"
    click Schemas "https://github.com/veenzent/scissor_url/blob/master/scissorapp/schemas.py"
    click RateLimiter "https://github.com/veenzent/scissor_url/blob/master/scissorapp/rate_limiter.py"
    click Config "https://github.com/veenzent/scissor_url/blob/master/scissorapp/instance/config.py"
    click Requirements "https://github.com/veenzent/scissor_url/blob/master/requirements.txt"
    click Tests "https://github.com/veenzent/scissor_url/blob/master/test_main.py"
```
