URL Service

A fullstack application for processing URL-checking jobs asynchronously.

Users can submit groups of URLs, monitor job progress, inspect per-URL results, and cancel unfinished work. The backend controls concurrency and request timeouts, while the frontend presents job state through a React dashboard.

Architecture

flowchart LR
    User[User] --> React[React application]
    React --> API[NestJS REST API]

    API --> JobService[Job service]
    JobService --> Scheduler[Concurrent URL scheduler]
    Scheduler --> Checker[HTTP URL checker]

    Checker --> Remote[Remote URLs]
    Checker --> Results[Per-URL results]
    Results --> JobService

    JobService --> JobState[In-memory job state]
    JobState --> API
    API --> React

    Contracts[Shared contracts] --> React
    Contracts --> API

Loading

Job lifecycle

stateDiagram-v2
    [*] --> Queued
    Queued --> Running
    Running --> Completed
    Running --> Failed
    Queued --> Cancelled
    Running --> Cancelled

Loading

Stack

Backend

• TypeScript
• NestJS
• RxJS
• Zod
• Swagger and OpenAPI
• class-validator
• class-transformer

Frontend

• React 18
• TypeScript
• Vite
• Zustand
• Tailwind CSS

Tooling

• npm workspaces
• Docker
• Docker Compose

Project structure

├── backend/       # NestJS application
├── frontend/      # React application
├── libs/
│   └── common/    # Shared request, response, and domain contracts
├── docker-compose.yml
├── package.json
└── README.md

Running Locally

cp backend/.env.example backend/.env
npm install
npm run build -w @url-service/common
npm run dev:back    # terminal 1
npm run dev:front   # terminal 2

Running with Docker

docker compose up --build

URLs

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000/api
• Swagger UI: http://localhost:3000/docs

API

Method	Path	Purpose
POST	/api/jobs	Create a job and start asynchronous URL validation
GET	/api/jobs	Get the list of jobs with their statuses and statistics
GET	/api/jobs/:id	Get detailed information for each URL in a job
DELETE	/api/jobs/:id	Cancel a job and stop processing URLs that have not started