URL Shortener

This project serves as a personal exploration and benchmark of full-stack development skills. It is a full-stack URL shortener application designed to provide a robust and efficient service for creating and managing short URLs. It's built as a monorepo, separating concerns between the client, server, and shared code.

Features

• URL Shortening: Create short, memorable links from long URLs.
• User Authentication: Secure user registration, login, and session management using JWTs and refresh tokens.
• User Management: (Presumed) Functionality to manage user accounts.
• Admin Privileges: (Presumed) Support for different privilege levels (e.g., admin users).
• API: A well-defined API for interacting with the service.

Technology Stack

The project leverages modern web technologies for a high-performance and maintainable codebase:

Backend (Server):

• Fastify: A fast and low-overhead web framework for Node.js.
• TypeScript: For type safety and better developer experience.
• SQLite: A lightweight, file-based SQL database for data persistence.
• argon2: For secure password hashing.
• jose: For JSON Web Token (JWT) handling.
• Zod: For runtime validation of API requests.

Frontend (Client):

• SvelteKit: A powerful framework for building web applications with Svelte.
• Svelte 5 (Runes): Utilizing the latest Svelte features for reactive UI development.
• TypeScript: For type safety.
• Vite: A fast build tool for modern web projects.
• Sass: For CSS pre-processing.

Shared (Monorepo Package):

• TypeScript: For shared types, interfaces, and constants.
• Zod: Shared validation schemas for consistent validation across client and server.

Monorepo Structure

The project is organized as a pnpm monorepo with the following main workspaces:

• apps/server: Contains the Fastify backend application, handling API requests, database interactions, and business logic.
• apps/client: Houses the SvelteKit frontend application, providing the user interface.
• packages/shared: A package containing code shared between the client and server, such as API endpoint constants, zod schemas for data validation, and common TypeScript types.

Getting Started (Development)

To get a local copy up and running, follow these simple steps.

1. Clone the repository:

   git clone https://github.com/misterabdul/url-shortener.git
   cd url-shortener

2. Install dependencies: This project uses pnpm workspaces. Ensure you have pnpm installed, then run:

   pnpm install

3. Set up environment variables: Copy the example environment files for both the client and server.

   cp apps/client/.env.example apps/client/.env
   cp apps/server/.env.example apps/server/.env
   # Edit the .env files with your desired configurations

4. Run in development mode: This command will start both the server and client in development mode, with hot-reloading. The Svelte frontend will be accessible at http://localhost:5173. The Fastify backend will run on the port defined in apps/server/.env (defaulting to 8080 if not specified).

   pnpm dev

Running with Docker (Standalone)

You can build and run this application as a single Docker container.

Prerequisites

• Docker

1. Build the Docker Image

Navigate to the root of the project and build the Docker image. You can tag it with a meaningful name, for example, url-shortener-app.

docker build -t url-shortener-app .

This command will use the Dockerfile in the project root to create a production-ready image for the application.

2. Run the Docker Container

Once the image is built, you can run a container from it. This command will:

• -p 8080:8080: Map port 8080 on your host machine to port 8080 inside the container.
• -v "$(pwd)"/volumes/data:/app/data: Mount a local directory (volumes/data) to /app/data inside the container for persistent database storage.
• --env-file ./.env: Load environment variables from your local .env file into the container.
• url-shortener-app: Specify the name of the image to run.

docker run -d \
  -p 8080:8080 \
  -v "$(pwd)"/volumes/data:/app/data \
  --env-file ./.env \
  url-shortener-app

The application will then be accessible in your web browser, typically at http://localhost:8080.

3. Manage the Container

• To view logs:

  docker logs <container_id_or_name> -f

• To stop the container:

  docker stop <container_id_or_name>

• To remove the container:

  docker rm <container_id_or_name>

  (Replace <container_id_or_name> with the actual ID or name of your running container.)

---

A Note on AI Contribution

Transparency is important. This project utilized AI-powered tools, specifically Google's Gemini, to assist in development.

• Documentation: The initial drafts of this README.md and the AGENTS.md file were generated with AI assistance.
• Code Review: The AI was also used to perform code reviews and suggest improvements to the codebase.

The core application logic, architectural decisions, and all final committed code were written and are fully owned by the human developer. The AI's role was that of a supportive tool, not the primary author.

For a detailed breakdown of the principles and nature of this collaboration, please see the AI Agent Contribution file.

License

This project is licensed under the MIT License. See the LICENSE file for details.