URL Shortener

API built with Django and Django REST Framework, it provides endpoints for creating, managing, and retrieving shortened URLs, also offers features for tracking clicks, groups, and plans, it integrates with various notification services and email services. The frontend is built with Next.js and Tailwind CSS, Auth.js, and HeroUI, it provides a responsive and user-friendly interface for users to interact with the API.

💻 General

🗃️ Repository

Clone the repository.

git@github.com:tyronejosee/project_url_shortener.git

🌱 Contribute

If you would like to contribute to the project:

1. Fork the repository.
2. Create a branch with the name of your feature: git checkout -b feature/new-feature.
3. Make your changes and commit: git commit -m 'feat: added new feature'.
4. Push your changes: git push origin feature/new-feature.
5. Open a Pull Request and submit your changes to the develop branch.

⚖️ License

This project is under the Apache License Licence.

🛠️ Backend

⚙️ Installation

Create a virtual environment (Optional, only if you have Python installed).

python -m venv env

Activate the virtual environment (Optional, only if you have Python installed).

env\Scripts\activate

Notes: (env) will appear in your terminal input.

Install all dependencies (Optional, only if you have Python installed).

pip install -r requirements/local.txt

Create a copy of the .env.example file and rename it to .env.

cp .env.example .env

Update the values of the environment variables (Important).

Note: Make sure to correctly configure your variables before building the container.

🐳 Docker

Build your container; it will take time the first time, as Docker needs to download all dependencies and build the image. Use the -d (detached mode) flag to start your containers in the background. Use the --build flag if you have changes and need to rebuild.

docker compose up
docker compose up -d
docker compose up --build

Stop the running containers (does not remove them).

docker compose stop

Start previously created and stopped containers.

docker compose start

Show container logs in real-time.

docker compose logs -f

Restart a service with issues (Replace <service_name>).

docker compose restart <service_name>

Remove your container.

docker compose down

🐍 Django

Access the web service console that runs Django.

docker compose exec web bash

Inside the Django console, create the migrations.

python manage.py makemigrations

Run the migrations.

python manage.py migrate

If you need to be more specific, use:

python manage.py migrate <app_label> <migration_name>

List all available migrations and their status.

python manage.py showmigrations

Note: Manually create the migration if Django skips an app; this happens because Django did not find the /migrations folder.

Create a superuser to access the entire site without restrictions.

python manage.py createsuperuser

Log in to dashboard:

http://127.0.0.1:8050/dashboard/

Access Swagger or Redoc.

http://127.0.0.1:8050/api/schema/swagger/
http://127.0.0.1:8050/api/schema/redoc/

🚨 Important Notes

Check the creation of migrations before creating them.

docker compose exec web python manage.py makemigrations users

Note: Checking migrations before their creation is necessary to avoid inconsistencies in user models.

🐘 PostgreSQL

Access the PostgreSQL console.

docker compose exec db psql -U <database_user> -d <database_name>

Note: -U User, -d Database

List all the tables in the database.

\dt

Show the detailed structure of a specific table.

\d <table_name>

Create a backup of your database (Optional).

docker compose exec web python manage.py dumpdata > backup.json

Load the created backup if needed (Optional).

docker compose exec web python manage.py loaddata

🎨 Frontend

The front-end of the application was created with Next.js using the App Router introduced in Next.js 15 and the package manager NPM.

✅ Requirements

• Node.js >= 22.11.0
• NPM >= 10.8.2

⚙️ Installation (Front-end)

Navigate to the frontend folder:

cd ./frontend/

Install the dependencies:

npm install

Available Scripts

Start the development server at http://localhost:3000/

npm run dev

Build the application for production.

npm run build

Start the server in production mode.

npm run start

Run the linter to check the code quality.

npm run lint

📂 App Router Setup

This project uses the App Router from Next.js to handle routing. Page files (page.tsx) are placed inside folders within the app/ directory. Example:

app/
├── page.tsx         # Main page at "/"
├── urls/
│   └── page.tsx     # URLs page at "/urls"

You can create new routes simply by adding folders inside app/ and adding page.tsx files for the views.

You can deploy this application on platforms like Vercel (the recommended one for Next.js), Netlify, or any other service that supports Node.js.

📦 Resources

Some resources used in this project:

• Django - Web framework in Python.
• Django REST Framework - REST APIs in Django.
• Django SES - Email backend in Python.
• Django Storages - Static and media files in Python.
• Swagger UI - API documentation in HTML.
• Redoc - API documentation in HTML.
• Ruff - Linter in Python.
• Pre-commit - Git hooks in Python.
• Next.js Documentation - Frontend framework in JavaScript.
• Prettier - Code formatter in JavaScript.
• Auth.js - Authentication library in JavaScript.
• Tailwind CSS - CSS framework in JavaScript.
• HeroUI - UI components in JavaScript.
• Lucide - Icons in JavaScript.
• Ko-Fi Widget - Donation widget in HTML.
• Ko-Fi Webhook - Webhooks for Ko-Fi.

Enjoy! 🎉