Book Tracking System is a comprehensive reading management application designed for book lovers who want to track their reading habits, organize their library, and gain insights into their reading patterns. Built with modern technologies and best practices, it provides a seamless experience across devices with rich visualizations and powerful features.

• 📊 Data-Driven Insights: Visualize your reading patterns with interactive charts and heatmaps
• 🎯 Goal-Oriented: Set reading goals and track progress with precision
• 🏷️ Organized: Categorize books with custom tags and manage multiple authors
• 📝 Rich Content: Add notes, summaries, and detailed information to your books
• 🚀 Modern Stack: Built with the latest versions of Angular, .NET, and PostgreSQL
• 🐳 Easy Deployment: One command to run the entire stack with Docker

• 📚 Book Management: Add, edit, and delete books with cover images, ratings, and detailed information
• ✍️ Author Management: Track authors with biographies, profile images, and their complete bibliography
• 🏷️ Tag System: Create custom tags to categorize and filter your books
• 📖 Reading Sessions: Log daily reading progress with page counts and notes
• 🎯 Reading Goals: Set targets and track completion with visual progress indicators
• 📅 Heatmap Calendar: GitHub-style heatmap showing your reading activity throughout the year

• 📊 Statistics Dashboard: Comprehensive analytics including books read, total pages, reading streaks, and trends
• 🔍 Smart Search: Quick search across books and authors
• 💡 Recommendations: Get personalized book recommendations based on your reading history
• 📝 Rich Text Notes: Add formatted notes to reading sessions and book summaries
• 📱 Responsive Design: Beautiful UI that works seamlessly on desktop, tablet, and mobile
• 🌓 Dark Mode: Eye-friendly dark theme support

The easiest way to run the Book Tracking System is using Docker. This method requires minimal setup and works on Windows, macOS, and Linux.

• Docker (20.10 or later)
• Docker Compose (included with Docker Desktop)

1. Clone the repository

   git clone <repository-url>
   cd Book-Tracking-System

2. Start the application (this will build and start all services)

   docker compose up -d

   What happens:

   • ✅ Builds optimized Docker images for frontend and backend
   • ✅ Pulls PostgreSQL 15 Alpine image
   • ✅ Creates persistent volume for database
   • ✅ Starts all three containers
   • ✅ Automatically applies database migrations
   • ✅ Waits for database to be ready before starting backend

3. Access the application

   • 🌐 Web App: http://localhost
   • 📡 API (Swagger): http://localhost:5000
   • 🗄️ Database: localhost:5432 (credentials in docker-compose.yml)

4. View logs (optional)

   # All services
   docker compose logs -f
   
   # Specific service
   docker compose logs -f frontend
   docker compose logs -f backend
   docker compose logs -f db

5. Stop the application

   docker compose down

6. Stop and remove all data (including database)

   docker compose down -v

If you modify the code, rebuild the images:

docker compose up -d --build

For active development, you may prefer running services locally.

• .NET 10 SDK: Download here
• Node.js 18+ (LTS): Download here
• PostgreSQL 15+: Download here

1. Navigate to backend directory

   cd backend

2. Install dependencies

   dotnet restore

3. Setup database

   • Create a PostgreSQL database named booktracking
   • Copy environment template:

     cp .env.example .env

   • Edit .env and set your connection string:

     DB_CONNECTION_STRING=Host=localhost;Port=5432;Database=booktracking;Username=postgres;Password=yourpassword

4. Apply migrations

   dotnet ef database update

5. Run the backend

   dotnet run

   Backend will be available at:

   • API: http://localhost:5162
   • Swagger: http://localhost:5162/swagger

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Configure API URL (if needed)

   Edit src/environments/environment.ts to point to your backend:

   export const environment = {
     production: false,
     rootUrl: 'http://localhost:5162',
     apiUrl: 'http://localhost:5162/api'
   };

4. Run the development server

   npm start
   # or: ng serve

   Frontend will be available at: http://localhost:4200

Backend:

cd backend
dotnet publish -c Release -o ./publish

Frontend:

cd frontend
npm run build
# Output in: dist/frontend/browser/

Book-Tracking-System/
│
├── 📂 backend/                    # ASP.NET Core API
│   ├── Controllers/               # REST API controllers
│   ├── Models/                    # Entity models (database)
│   ├── DTOs/                      # Data Transfer Objects
│   ├── Services/                  # Business logic layer
│   ├── Repository/                # Data access layer
│   ├── Data/                      # DbContext
│   ├── Migrations/                # EF Core migrations
│   ├── Profiles/                  # AutoMapper profiles
│   ├── ValidationAttributes/      # Custom validation
│   ├── Dockerfile                 # Backend container image
│   ├── Program.cs                 # Application entry point
│   ├── .env.example               # Environment template
│   └── README.md                  # Backend documentation
│
├── 📂 frontend/                   # Angular SPA
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/        # UI components
│   │   │   ├── services/          # HTTP & state services
│   │   │   ├── models/            # TypeScript interfaces
│   │   │   ├── directives/        # Custom directives
│   │   │   ├── app.routes.ts      # Routing configuration
│   │   │   └── app.config.ts      # App configuration
│   │   ├── environments/          # Environment configs
│   │   ├── assets/                # Images, icons, etc.
│   │   └── styles.css             # Global styles
│   ├── Dockerfile                 # Frontend container image
│   ├── nginx.conf                 # Nginx configuration
│   └── README.md                  # Frontend documentation
│
├── 📂 docs/                       # Project documentation
│   ├── 01_API_Specification.md
│   ├── 02_Database_Schema.md
│   ├── 03_Product_Requirements.md
│   ├── 04_Technical_Specification.md
│   └── 05_User_Stories.md
│
├── 📄 docker-compose.yml          # Container orchestration
├── 📄 CONTRIBUTING.md             # Contribution guidelines
├── 📄 LICENSE                     # License information
└── 📄 README.md                   # This file

┌──────────────────────────────────────────────────────────┐
│                        User Browser                       │
└───────────────────────┬──────────────────────────────────┘
                        │ HTTP :80
                        ▼
┌──────────────────────────────────────────────────────────┐
│              Frontend Container (Nginx)                   │
│  ┌────────────────────────────────────────────────────┐  │
│  │           Angular 20 Application                   │  │
│  │  • Components • Services • Routing • State        │  │
│  └────────────────────────────────────────────────────┘  │
└───────────────────────┬──────────────────────────────────┘
                        │ REST API :5000
                        ▼
┌──────────────────────────────────────────────────────────┐
│           Backend Container (ASP.NET Core)               │
│  ┌────────────────────────────────────────────────────┐  │
│  │              REST API Layer                        │  │
│  │          Controllers + Swagger Docs                │  │
│  ├────────────────────────────────────────────────────┤  │
│  │           Business Logic Layer                     │  │
│  │    Services + Validation + AutoMapper              │  │
│  ├────────────────────────────────────────────────────┤  │
│  │          Data Access Layer                         │  │
│  │    Repositories + EF Core + Migrations             │  │
│  └────────────────────────────────────────────────────┘  │
└───────────────────────┬──────────────────────────────────┘
                        │ PostgreSQL :5432
                        ▼
┌──────────────────────────────────────────────────────────┐
│          Database Container (PostgreSQL 15)              │
│  ┌────────────────────────────────────────────────────┐  │
│  │        Persistent Volume (postgres_data)           │  │
│  │  • Authors  • Books  • Tags  • Sessions  • Goals  │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

• 3-Tier Architecture: Clear separation between presentation, business logic, and data layers
• Repository Pattern: Abstraction over data access logic
• Service Layer: Centralized business logic
• DTO Pattern: Separation of API contracts from domain models
• Dependency Injection: Loose coupling and testability

The PostgreSQL database includes the following main entities:

Indexes:

• Foreign keys for efficient joins
• Date columns for quick filtering
• Composite indexes on frequently queried combinations

See Database Schema Documentation for detailed information.

The backend provides a comprehensive REST API documented with Swagger/OpenAPI.

• Docker: http://localhost:5000
• Local Dev: http://localhost:5162/swagger

See API Specification for complete endpoint details.

1. Frontend Image (~55MB)

   • Base: node:lts (build stage) + nginx:alpine (runtime)
   • Multi-stage build for optimal size
   • Production-optimized Angular build

2. Backend Image (~245MB)

   • Base: mcr.microsoft.com/dotnet/sdk:10.0 (build) + mcr.microsoft.com/dotnet/aspnet:10.0 (runtime)
   • Includes automatic migration runner with retry logic

3. Database Image

   • Official postgres:15-alpine
   • Persistent volume: postgres_data

Edit docker-compose.yml to customize:

services:
  db:
    environment:
      POSTGRES_USER: your_username      # Change this
      POSTGRES_PASSWORD: your_password  # Change this
      POSTGRES_DB: booktracking
  
  backend:
    environment:
      - DB_CONNECTION_STRING=Host=db;Port=5432;Database=booktracking;Username=your_username;Password=your_password

# Start all services
docker compose up -d

# Start specific service
docker compose up -d frontend

# Rebuild all images
docker compose build

# Rebuild and start
docker compose up -d --build

# View logs
docker compose logs -f [service_name]

# Stop all services
docker compose down

# Stop and remove volumes (deletes database!)
docker compose down -v

# Execute command in running container
docker compose exec backend dotnet ef migrations add MigrationName
docker compose exec db psql -U postgres -d booktracking

# View running containers
docker compose ps

• API Specification - Complete API reference
• Database Schema - Database structure and relationships
• Product Requirements - Feature specifications
• Technical Specification - Architecture and design
• User Stories - User-centric feature descriptions
• Frontend README - Frontend-specific documentation
• Backend README - Backend-specific documentation

• Default PostgreSQL credentials in docker-compose.yml
• CORS policy allows all origins
• Swagger enabled in production builds

• Change database credentials
• Configure specific CORS origins
• Enable HTTPS/TLS
• Set up environment-specific configurations
• Implement authentication (JWT planned)
• Configure proper logging and monitoring
• Set up database backups
• Use secrets management (Docker secrets, Azure Key Vault, etc.)

Contributions are welcome! Please read CONTRIBUTING.md for:

• Code of Conduct
• Development workflow
• Coding standards
• Pull request process

This project is licensed under the terms specified in the LICENSE file.

Problem: docker: command not found

• Solution: Install Docker Desktop from docker.com

Problem: Port 80 or 5000 already in use

• Solution: Stop the service using that port, or modify ports in docker-compose.yml

Problem: Frontend can't connect to backend

• Solution: Check that environment.prod.ts has correct API URL (default: http://localhost:5000/api)

Problem: Database migration fails

• Solution: Backend retries 10 times with 5-second intervals. Check docker compose logs backend for errors.

Problem: Changes not reflected after rebuild

• Solution: Use docker compose up -d --build --force-recreate

• 🐛 Bug Reports: Open an issue on GitHub
• 💡 Feature Requests: Submit an issue with the enhancement label
• 💬 Questions: Use GitHub Discussions