# bili20/encurtador-de-url architecture

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

- Interactive diagram: https://gitdiagram.com/bili20/encurtador-de-url
- Repository: https://github.com/bili20/encurtador-de-url

## Overview

##### Project Type and Purpose
- This is a full-stack web application: a URL shortener built with Node.js/TypeScript on the backend and a minimal frontend (static HTML/JS/CSS).
- It exposes HTTP endpoints to shorten URLs, redirect requests, implements rate limiting, caching, and scheduled jobs for popular-URL optimization.

##### File Structure
- src/
- config/db → PostgreSQL (Knex) and Redis connection setup
- controller → Express controllers for URL shortening and redirection
- middlewares → rateLimit.ts (uses Redis to throttle)
- model → URL data model and repository interface
- repository → PostgreSQL repository implementation
- service → business logic (generate short IDs, validate, cache check/write)
- jobs → scheduled tasks (cachesPopular.ts runs periodically to pre-cache hot URLs in Redis)
- routes → wires controllers to Express router
- app.ts → initializes Express, loads middleware, routes, error handling
- views/ → static frontend files (HTML + script.ts → compiled JS, CSS)
- docker-compose.yml → orchestrates three containers: app, PostgreSQL, Redis
- sample.env → environment variables (DB credentials, Redis URL, rate limit thresholds)

##### Extract Key Points from the README
- Tech Stack: Node.js, TypeScript, Express, Knex.js, PostgreSQL, Redis, Docker
- Features: URL shortening, rate limiting, redirect, simple UI, copy-to-clipboard, auto-cache popular URLs, scheduled jobs

a. Main Components
1. Client (Browser) – static UI served by Express + user interaction
2. API Server (Express/TypeScript)
3. PostgreSQL Database (persistent URL mappings)
4. Redis Cache (hot URL lookup & rate-limit counters)
5. Job Scheduler (cron job inside the same container or a separate worker process)
6. Infrastructure Orchestration (Docker Compose)

b. Relationships & Data Flows
- Browser → HTTP POST /shorten → Rate-Limit Middleware → Controller → Service
- Service checks Redis cache → if miss, writes to PostgreSQL via Repository → returns short code
- Browser → HTTP GET /:shortCode → Controller → Service
- Service checks Redis cache → if hit, redirect immediately
- if miss, query PostgreSQL → set Redis → redirect
- Job Scheduler (cachesPopular.ts)
- Periodically queries PostgreSQL for most-accessed URLs → populates Redis keys
- Rate-Limit Middleware
- On each incoming request, increments a Redis counter per IP → rejects if threshold exceeded

c. Architectural Patterns & Principles
- Layered architecture (Controller → Service → Repository → DB)
- Interface-based repository (urlsRepository.interface.ts) enabling swap of persistence layer
- Cache-Aside pattern for Redis (check-then-load then write)
- Middleware pipeline in Express
- Docker-based isolation of services

d. Key Technologies & Frameworks
- Node.js + Express (HTTP server)
- TypeScript (static typing)
- Knex.js (SQL query builder)
- PostgreSQL (relational persistence)
- Redis (caching & rate limiting)
- Docker Compose (local multi-container orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Compose"
        style DockerCompose fill:none,stroke:#555,stroke-dasharray:5 5
        subgraph "App Container"
            subgraph "UI Layer"
                Client["Client (Browser)"]:::client
                HTML["index.html"]:::static
                Script["script.js"]:::static
                Style["style.css"]:::static
                Client --> HTML
                Client --> Script
                Client --> Style
            end
            subgraph "Backend"
                App["app.ts"]:::server
                subgraph "Routes"
                    UrlRoutes["url.routes.ts"]:::server
                    IndexRoutes["index.routes.ts"]:::server
                end
                RateLimit["rateLimit.ts"]:::middleware
                Controller["url.controller.ts"]:::controller
                Service["urls.service.ts"]:::service
                RepoInterface["urlsRepository.interface.ts"]:::model
                RepoImpl["urlsRepository.ts"]:::repository
                Model["urls.ts"]:::model
                DBConfig["configDb.ts"]:::config
                RedisConfig["redis.ts"]:::config
                App --> UrlRoutes
                App --> IndexRoutes
                UrlRoutes --> RateLimit
                UrlRoutes --> Controller
                IndexRoutes --> Controller
                RateLimit --> Controller
                Controller --> Service
                Service --> RedisConfig
                Service --> RepoInterface
                RepoInterface --> RepoImpl
                RepoImpl --> DBConfig
                RepoImpl --> Model
            end
            Scheduler["cachesPopular.ts"]:::scheduler
            sampleEnv["sample.env"]:::config
        end
        Postgres["PostgreSQL"]:::db
        Redis["Redis Cache"]:::cache
    end

    Client -->|POST /shorten| App
    Client -->|GET /:shortCode| App
    Service -->|Check cache| Redis
    Service -->|Cache miss| Postgres
    Service -->|Set cache| Redis
    RepoImpl -->|Query| Postgres
    Scheduler -->|Query popular| Postgres
    Scheduler -->|Populate cache| Redis
    RateLimit -->|Rate-limit counters| Redis

    click HTML "https://github.com/bili20/encurtador-de-url/blob/main/views/index.html"
    click Script "https://github.com/bili20/encurtador-de-url/blob/main/views/script.js"
    click Style "https://github.com/bili20/encurtador-de-url/blob/main/views/style.css"
    click App "https://github.com/bili20/encurtador-de-url/blob/main/src/app.ts"
    click UrlRoutes "https://github.com/bili20/encurtador-de-url/blob/main/src/routes/url.routes.ts"
    click IndexRoutes "https://github.com/bili20/encurtador-de-url/blob/main/src/routes/index.routes.ts"
    click Controller "https://github.com/bili20/encurtador-de-url/blob/main/src/controller/url.controller.ts"
    click RateLimit "https://github.com/bili20/encurtador-de-url/blob/main/src/middlewares/rateLimit.ts"
    click Service "https://github.com/bili20/encurtador-de-url/blob/main/src/service/urls.service.ts"
    click RepoInterface "https://github.com/bili20/encurtador-de-url/blob/main/src/model/urlsRepository.interface.ts"
    click RepoImpl "https://github.com/bili20/encurtador-de-url/blob/main/src/repository/urlsRepository.ts"
    click Model "https://github.com/bili20/encurtador-de-url/blob/main/src/model/urls.ts"
    click DBConfig "https://github.com/bili20/encurtador-de-url/blob/main/src/config/db/configDb.ts"
    click RedisConfig "https://github.com/bili20/encurtador-de-url/blob/main/src/config/db/redis.ts"
    click Scheduler "https://github.com/bili20/encurtador-de-url/blob/main/src/jobs/cachesPopular.ts"
    click sampleEnv "https://github.com/bili20/encurtador-de-url/blob/main/sample.env"
    click Postgres "https://github.com/bili20/encurtador-de-url/blob/main/docker-compose.yml"
    click Redis "https://github.com/bili20/encurtador-de-url/blob/main/docker-compose.yml"

    classDef client fill:#9f6,stroke:#333
    classDef server fill:#bbf,stroke:#333
    classDef middleware fill:#f9f,stroke:#333
    classDef controller fill:#ddf,stroke:#333
    classDef service fill:#aff,stroke:#333
    classDef repository fill:#bdf,stroke:#333
    classDef model fill:#fed,stroke:#333
    classDef config fill:#fdb,stroke:#333
    classDef scheduler fill:#cfa,stroke:#333
    classDef db fill:#f96,stroke:#333
    classDef cache fill:#6cf,stroke:#333
    classDef static fill:#cff,stroke:#333
    classDef orchestration fill:none,stroke:#555,stroke-dasharray:5 5
```
