ByBook Monorepo Full Stack Project - Software Developer Assignment

A comprehensive book management application built with Go backend and modern web technologies. The project features a robust API for book management and advanced URL cleaning capabilities.

Frontend Application

• ⚡ Next.js 15.3.3: with Turbopack
• 🎨 Modern UI Components: Built with shadcn/ui (Radix UI) and Tailwind CSS
• 📱 Responsive Design: Mobile-first responsive layout
• 🔄 State Management: React Context and React Query for server state management
• 📡 API Integration: Axios-based service layer for backend communication
• 🎯 TypeScript: Full type safety across the application
• 🎨 Component Library: Reusable UI components with shadcn/ui
• 📖 Book Management Pages: Create, view, and manage books
  • Dynamic routing for book details
  • Form validation and error handling
  • Loading states and user feedback

Backend Application

• 📚 Book Management Module: Complete CRUD operations for book management

  • Create, read, update, and delete books
  • PostgreSQL database with UUID-based primary keys
  • Comprehensive input validation
  • Structured logging and error handling

• 🔗 URL Cleaner Module: Advanced URL processing service

  • Canonical URL cleaning (removes query parameters and fragments)
  • Redirect resolution to final destinations
  • Comprehensive cleaning operations
  • Input validation and error handling

Backend Infrastructure

• 🐳 Docker Support: Containerized deployment with Docker Compose
• 📋 Swagger Documentation: Interactive API documentation
• 🧪 Comprehensive Testing: Unit tests for all services
• 🏗️ Clean Architecture: Modular design with dependency injection
• � Database Migrations: Automated PostgreSQL schema management

📁 Project Structure

bybook/
├── apps/
│   ├── backend/                     # Go backend API
│   │   ├── api/
│   │   │   └── docs/                # Generated Swagger documentation
│   │   │       ├── docs.go
│   │   │       ├── swagger.json
│   │   │       └── swagger.yaml
│   │   ├── bin/                     # Compiled binaries (optional, usually in .gitignore)
│   │   ├── cmd/
│   │   │   └── main.go              # Application entry point
│   │   ├── internal/                # Private application code
│   │   │   ├── books/               # Book management module
│   │   │   │   ├── constants.go
│   │   │   │   ├── controller.go
│   │   │   │   ├── model.go
│   │   │   │   ├── repository.go
│   │   │   │   ├── routes.go
│   │   │   │   ├── service.go
│   │   │   │   └── validator.go
│   │   │   ├── urlcleaner/          # URL cleaning module
│   │   │   │   ├── constants.go
│   │   │   │   ├── controller.go
│   │   │   │   ├── errors.go
│   │   │   │   ├── model.go
│   │   │   │   ├── routes.go
│   │   │   │   ├── service.go
│   │   │   │   └── validator.go
│   │   │   └── di/                  # Dependency injection
│   │   │       ├── books_di.go
│   │   │       ├── container.go
│   │   │       └── urlcleaner_di.go
│   │   ├── migrations/              # Database migrations
│   │   │   ├── 000_enable_extensions.up.sql
│   │   │   ├── 000_enable_extensions.down.sql
│   │   │   ├── 001_create_books.up.sql
│   │   │   └── 001_create_books.down.sql
│   │   ├── pkg/                     # Shared packages
│   │   │   ├── db/
│   │   │   │   └── postgres.go
│   │   │   ├── env/
│   │   │   │   └── env.go
│   │   │   ├── logger/
│   │   │   │   └── logger.go
│   │   │   ├── middleware/
│   │   │   │   └── logging.go
│   │   │   └── routes/
│   │   │       └── routes.go
│   │   ├── tests/                   # Unit & integration tests
│   │   │   └── api/
│   │   │       ├── books/
│   │   │       │   └── books_service_test.go
│   │   │       └── urlcleaner/
│   │   │           └── urlcleaner_test.go
│   │   ├── vendor/                  # Vendored dependencies (optional)
│   │   ├── go.mod
│   │   ├── go.sum
│   │   ├── Makefile
│   │   └── README.md                # Backend-specific documentation
│   └── frontend/                    # Next.js Frontend Application
│       ├── src/
│       │   ├── app/                 # Next.js App Router
│       │   │   ├── page.tsx         # Home page
│       │   │   ├── layout.tsx       # Root layout
│       │   │   ├── loading.tsx      # Loading UI
│       │   │   └── books/           # Book management pages
│       │   │       ├── [id]/        # Dynamic book pages like detail and edit
│       │   │       └── create/      # Create book page
│       │   ├── components/          # Reusable UI components
│       │   │   ├── common/          # Common components (BookCard, BookForm, etc.)
│       │   │   ├── layout/          # Layout components
│       │   │   ├── navigation/      # Navigation components
│       │   │   ├── pages/           # Page-specific components
│       │   │   ├── providers/       # Context providers
│       │   │   └── ui/              # shadcn/ui components
│       │   ├── contexts/            # React contexts
│       │   │   └── BookContext/     # Book state management
│       │   ├── hooks/               # Custom React hooks
│       │   │   ├── useBookContext/  # Book context hook
│       │   │   ├── useBookForm/     # Book form management
│       │   │   └── useBooks/        # Book data fetching
│       │   ├── lib/                 # Utility libraries
│       │   │   ├── routes.ts        # Route definitions
│       │   │   └── utils.ts         # Utility functions
│       │   ├── services/            # API service layer
│       │   │   └── bookService.ts   # Book API calls
│       │   └── types/               # TypeScript type definitions
│       │       └── book.ts          # Book type definitions
│       ├── public/                  # Static assets
│       ├── package.json
│       ├── next.config.ts
│       ├── tailwind.config.js
│       ├── tsconfig.json
│       └── README.md                # Frontend-specific documentation
├── docker-compose.yml              # Docker orchestration for local dev
├── Makefile                        # Root-level build automation
├── .env                            # Environment variables
└── README.md                       # Monorepo documentation (you are here)

🛠️ Installation & Setup

Prerequisites

• Docker & Docker Compose: For containerized deployment
• Go: 1.24.4+ (for local backend development)
• PostgreSQL: 12+ (for local database)
• Node.js: 18+ (for frontend development)
• pnpm: Package manager for frontend dependencies

Quick Start with Docker Compose

1. Clone the repository:

   git clone https://github.com/metecan/bybook.git
   cd bybook

2. Set up environment variables: Create a .env file in the root directory:

   # Database Configuration
   DB_USER=postgres
   DB_PASSWORD=1234
   DB_NAME=postgres
   
   # Application Ports
   FRONTEND_PORT=3000
   BACKEND_PORT=8080

3. Start the all applications: (It will build the images and start the containers) Using the provided Makefile:

   make up

   Or without make:

   docker-compose up --build

4. Access the application:

   • Backend API: http://localhost:8080
   • Swagger Documentation: http://localhost:8080/swagger/index.html
   • Frontend: http://localhost:3000

Local Development Setup

Frontend Development

1. Navigate to frontend directory:

   cd apps/frontend

2. Install dependencies:

   pnpm install

3. Start the development server:

   pnpm dev

4. Build for production:

   pnpm build
   pnpm start

Backend Development

1. Navigate to backend directory:

   cd apps/backend

2. Install dependencies:

   go mod tidy

3. Set up PostgreSQL database:

   # Using Docker
   docker run --name postgres-bybook \
     -e POSTGRES_PASSWORD=1234 \
     -e POSTGRES_DB=postgres \
     -p 5432:5432 \
     -d postgres:15

4. Run database migrations: (Dockerfile handles this automatically)

   # Execute SQL files in order:
   # 1. migrations/000_enable_extensions.up.sql
   # 2. migrations/001_create_books.up.sql

5. Start the backend server:

   make run-dev

🔌 API Endpoints

Books Management API

Method	Endpoint	Description	Authentication
GET	/api/books	Get all books	None
GET	/api/books/:id	Get book by ID	None
POST	/api/books	Create a new book	None
PUT	/api/books/:id	Update existing book	None
DELETE	/api/books/:id	Delete book	None

Example Requests

Create Book:

curl -X POST http://localhost:8080/api/books \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The Great Gatsby",
    "author": "F. Scott Fitzgerald",
    "year": 1925
  }'

Get All Books:

curl http://localhost:8080/api/books

URL Cleaner API

Method	Endpoint	Description	Authentication
POST	/api/url/clean	Clean and process URL	None

Cleaning Operations

• canonical: Removes query parameters and fragments
• redirect: Resolves redirects to final destination
• all: Applies both canonical and redirect operations

Example Request

curl -X POST http://localhost:8080/api/url/clean \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/path?utm_source=google&param=value",
    "operation": "canonical"
  }'

Response:

{
  "data": {
    "processed_url": "https://example.com/path"
  },
  "message": "URL cleaned successfully"
}

🧪 Testing

Running Tests

# Run all backend tests
cd apps/backend
go test ./...

# Run with verbose output
go test -v ./...

# Run specific module tests
go test ./tests/api/books/
go test ./tests/api/urlcleaner/

# Run with coverage
go test -cover ./...

Test Coverage

• ✅ Books Module: CRUD operations, validation, error handling
• ✅ URL Cleaner Module: All cleaning operations, input validation
• ✅ Service Layer: Business logic and data processing
• ✅ Repository Layer: Data access and persistence

🐳 Docker Deployment

Docker Compose Commands

# Start all services
make up

# Stop all services
make down

# Restart services
make restart

# View logs
docker-compose logs -f

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

Manual Docker Commands

# Build backend image
docker build -f apps/backend/Dockerfile.backend -t bybook-backend apps/backend

# Run backend container
docker run -p 8080:8080 bybook-backend

# Run PostgreSQL
docker run --name postgres \
  -e POSTGRES_PASSWORD=1234 \
  -e POSTGRES_DB=postgres \
  -p 5432:5432 \
  -d postgres:15

🔧 Development

Available Make Commands

Root Level:

make up      # Start all services with Docker Compose
make down    # Stop all services
make restart # Restart all services

Backend (apps/backend/):

make build     # Build the application
make run       # Run in production mode  
make run-dev   # Run in development mode
make docs      # Generate Swagger documentation

Environment Variables

Variable	Description	Default	Required
DB_USER	PostgreSQL username	postgres	Yes
DB_PASSWORD	PostgreSQL password	-	Yes
DB_NAME	PostgreSQL database name	postgres	Yes
BACKEND_PORT	Backend server port	8080	No
FRONTEND_PORT	Frontend server port	3000	No

Database Schema

-- Books table
CREATE TABLE books (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(255) NOT NULL,
    author VARCHAR(255) NOT NULL,
    year INT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);

📖 Documentation

• Swagger UI: http://localhost:8080/swagger/index.html
• API Specification: Generated automatically from code annotations

🏗️ Architecture

Backend Architecture

The backend follows clean architecture principles:

1. Controllers: HTTP request handling and response formatting
2. Services: Business logic implementation
3. Repositories: Data access layer abstraction
4. Models: Data transfer objects and entities
5. Dependency Injection: Modular component management

Technology Stack

• Backend: Go 1.24.4, Fiber v2, PostgreSQL
• Frontend: Next.js 15.3.3, React 19, TypeScript 5
• UI/Styling: Tailwind CSS 4, Radix UI, shadcn/ui
• State Management: React Query (TanStack Query), React Context
• Development Tools: ESLint, Prettier, Turbopack
• Testing: Testify (Backend), custom mocks
• Documentation: Swagger/OpenAPI 3.0
• Database: PostgreSQL with UUID support
• Containerization: Docker, Docker Compose

🚀 Deployment

Production Deployment

1. Environment Setup: Configure production environment variables
2. Database: Use managed PostgreSQL service
3. Application: Deploy using Docker containers
4. Monitoring: Implement health checks and logging
5. Security: Add authentication/authorization as needed

---

Screenshots

Swagger Documentation

---

Frontend Application

---

URL Cleaner API

---

Deployment

---

Video

Watch Video

Last Updated (18 Jun 2025, 17:00)