Faviconer

A full-stack application for finding favicons from domain CSV files. Built with NestJS backend and Next.js frontend.

Thought Process & Architecture

View the interactive architecture diagram and thought process on Excalidraw:

📐 View Architecture Diagram

This diagram illustrates the system design, component relationships, and decision-making process behind the application architecture.

Quick Start with Docker (Recommended)

The easiest way to run the application locally is using Docker Compose. This will set up both frontend and backend automatically.

Prerequisites

• Docker 20.x or higher
• Docker Compose 2.x or higher
• Node.js 20.x (if running without Docker)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd faviconer.by.yerick

2. Optional: Configure environment variables

   Create backend/.env file if you want to use database caching:

   DATABASE_URL="postgresql://postgres:password@postgres:5432/faviconer?sslmode=disable"
   PORT=3001

   Note: Database is optional. The app works without it using HTTP strategies.

3. Start the application:

   docker-compose up --build

4. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001
   • Health Check: http://localhost:3001/api/favicons/health

Docker Commands

# Start services
docker-compose up

# Start in detached mode (background)
docker-compose up -d

# Rebuild and start
docker-compose up --build

# Stop services
docker-compose down

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f backend
docker-compose logs -f frontend

# Stop and remove volumes
docker-compose down -v

Optional: Enable Database Caching

If you want to use PostgreSQL for caching favicons:

1. Uncomment the postgres service in docker-compose.yml
2. Uncomment the DATABASE_URL in the backend environment section
3. Update the DATABASE_URL to use the postgres service:

   - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/faviconer?sslmode=disable

4. Run database migrations:

   docker-compose exec backend yarn prisma:migrate dev

Manual Setup (Without Docker)

If you prefer to run the application without Docker, see the individual README files:

• Backend Setup: See backend/README.md
• Frontend Setup: See frontend/README.md

Project Structure

faviconer.by.yerick/
├── backend/          # NestJS API server
│   ├── src/         # Source code
│   ├── prisma/      # Database schema (optional)
│   └── Dockerfile   # Backend container definition
├── frontend/         # Next.js frontend application
│   ├── app/         # Next.js app directory
│   └── Dockerfile   # Frontend container definition
├── docker-compose.yml # Docker Compose configuration
└── README.md         # This file

Features

• CSV Upload: Upload CSV files with domain lists
• Real-time Progress: Server-Sent Events (SSE) for live progress updates
• Multiple Discovery Strategies: HTTP requests, HTML parsing, database caching
• Database Caching (Optional): Cache found favicons for faster subsequent lookups
• Results Table: Filterable, paginated table with favicon previews
• CSV Export: Download results as CSV file
• Responsive Design: Works on desktop and mobile devices
• Dark Mode: Built-in dark mode support

API Endpoints

• POST /api/favicons/process - Upload CSV and start processing
• GET /api/favicons/stream/:jobId - Stream progress updates (SSE)
• GET /api/favicons/health - Health check endpoint

Technology Stack

Backend:

• NestJS
• TypeScript
• Prisma (optional, for database)
• PostgreSQL (optional, via Supabase or local)

Frontend:

• Next.js 16
• React 19
• Material-UI (MUI) v7
• TypeScript
• Sass

Development

For development setup and detailed instructions, see:

• Backend README
• Frontend README

License

MIT