AGENTS.md - AI Assistant Guide

This file contains essential context for AI assistants working on the Reading Tracker project.

Project Overview

Name: Reading Tracker
Type: Full-stack web application for tracking personal reading habits
Architecture: Monorepo with separate backend and frontend directories
Status: Fully functional, actively maintained

Technology Stack

Backend (/backend)

• Runtime: Node.js 18+
• Framework: Express.js
• Database: PostgreSQL 16 (running in Podman/Docker container)
• ORM: Raw SQL queries with pg library
• External APIs: Google Books API
• Key Dependencies:
  • express - Web framework
  • pg - PostgreSQL client
  • axios - HTTP client for Google Books API
  • cors - CORS middleware
  • dotenv - Environment variables

Frontend (/frontend)

• Framework: Vue 3 with Composition API (<script setup>)
• Build Tool: Vite
• Styling: Tailwind CSS v4 (using @tailwindcss/vite plugin, NOT PostCSS)
• Routing: Vue Router
• State Management: Pinia (configured but minimal usage)
• Charts: Chart.js + vue-chartjs
• HTTP Client: Axios
• Key Pattern: All components use Composition API with <script setup> syntax

Database

• System: PostgreSQL 16
• Container: Managed via ./db.sh helper script
• Connection: Default localhost:5432
• Management: Podman (Docker compatible)

Directory Structure

ReadingTracker/
├── backend/                    # Express API server
│   ├── config/db.js           # Database connection pool
│   ├── routes/
│   │   ├── books.js           # Book CRUD + Google Books search
│   │   └── stats.js           # Statistics endpoints
│   ├── services/
│   │   └── bookApiService.js  # Google Books API integration
│   ├── server.js              # Main entry point
│   ├── .env                   # Environment config (NOT in git)
│   └── package.json
│
├── frontend/                   # Vue 3 SPA
│   ├── src/
│   │   ├── assets/
│   │   │   └── main.css       # Tailwind CSS config with @theme
│   │   ├── components/
│   │   │   └── MonthlyPagesChart.vue
│   │   ├── router/index.js
│   │   ├── services/api.js    # Axios API client
│   │   ├── stores/            # Pinia stores (minimal usage)
│   │   ├── utils/
│   │   │   └── isbnDetector.js
│   │   └── views/
│   │       ├── Dashboard.vue
│   │       ├── BooksView.vue
│   │       └── AddBookView.vue
│   ├── vite.config.js         # Uses @tailwindcss/vite plugin
│   ├── .env                   # Environment config (NOT in git)
│   └── package.json
│
├── migrations/                 # Database migration files
├── docs/                      # Original architecture docs
├── init-db.sql                # Database schema
├── db.sh                      # Database helper script
└── docker-compose.yml         # PostgreSQL container config

Database Schema

books Table

CREATE TABLE books (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    author VARCHAR(255),
    pages INTEGER,
    genres TEXT[],              -- PostgreSQL array type
    isbn VARCHAR(20),
    cover_url VARCHAR(500),
    source VARCHAR(20),         -- 'manual' or 'google_books'
    start_date DATE,            -- When user started reading
    end_date DATE,              -- When user finished reading
    created_at TIMESTAMP DEFAULT NOW()
);

Indexes

• idx_books_start_date on start_date
• idx_books_end_date on end_date

Important Implementation Details

1. Tailwind CSS v4 Configuration

• DO NOT create tailwind.config.js or postcss.config.js
• Configuration is in frontend/src/assets/main.css using @theme directive
• Uses @tailwindcss/vite plugin in vite.config.js
• Import: @import "tailwindcss"; (NOT @tailwind base; @tailwind components;)

2. Vue Composition API

• ALL components use <script setup> syntax
• Use ref() for primitive reactive values
• Use reactive() for objects
• Import lifecycle hooks: onMounted, onUnmounted, etc.
• Router: const router = useRouter() then router.push()
• Route params: const route = useRoute() then route.params.id

3. Date Handling

• Database stores dates as PostgreSQL DATE type
• Frontend displays in Norwegian format: dd.mm.yyyy
• HTML5 date inputs for user input
• Format function: toLocaleDateString('nb-NO', { day: '2-digit', month: '2-digit', year: 'numeric' })

4. Google Books API

• Service: backend/services/bookApiService.js
• No API key required (rate-limited)
• Optional API key via GOOGLE_BOOKS_API_KEY env var
• Search endpoint: /api/books/search?q=query
• ISBN endpoint: /api/books/isbn/:isbn

5. PostgreSQL Arrays

• Genres stored as TEXT[] array type
• Query with UNNEST() for statistics
• Insert/Update: ARRAY['Genre1', 'Genre2']
• Frontend: Comma-separated string converted to array

Environment Configuration

Development Mode (default)

Frontend: http://localhost:5173 (Vite dev server)
Backend:  http://localhost:3000
Database: localhost:5432

Backend .env:

DATABASE_URL=postgresql://reading_user:reading_pass@localhost:5432/reading_tracker
PORT=3000
CORS_ORIGIN=http://localhost:5173
NODE_ENV=development
GOOGLE_BOOKS_API_KEY=

Frontend .env:

VITE_API_URL=http://localhost:3000/api

Docker Mode

Frontend: http://localhost:8080 (nginx)
Backend:  http://localhost:3000
Database: postgres:5432 (Docker network)

Common Development Tasks

Adding a New API Endpoint

1. Create route handler in backend/routes/
2. Register route in backend/server.js
3. Add API method to frontend/src/services/api.js
4. Use in Vue components

Adding a New Vue Component

1. Create .vue file in frontend/src/components/ or frontend/src/views/
2. Use <script setup> syntax
3. Import ref, reactive, computed as needed
4. Use Tailwind utility classes (no <style> sections)
5. If page component, add route to frontend/src/router/index.js

Modifying Database Schema

1. Create migration SQL file in migrations/
2. Apply with: podman exec -i reading-tracker-db psql -U reading_user -d reading_tracker < migrations/filename.sql
3. Update relevant backend routes/queries
4. Update frontend forms/displays

Adding Statistics

1. Add SQL query to backend/routes/stats.js
2. Use proper date functions: DATE_TRUNC(), EXTRACT()
3. For genres: Use UNNEST(genres) to query array
4. Add API method to frontend/src/services/api.js
5. Display in Dashboard.vue or new component

API Endpoints Reference

Books

• GET /api/books - List all books from database
• GET /api/books/:id - Get single book
• POST /api/books - Create book
• PUT /api/books/:id - Update book
• DELETE /api/books/:id - Delete book
• GET /api/books/search?q=query&maxResults=10 - Search Google Books
• GET /api/books/isbn/:isbn - Get book by ISBN from Google Books

Statistics

• GET /api/stats/dashboard - Dashboard overview (counts, averages, top genres)
• GET /api/stats/monthly - Last 12 months of reading data
• GET /api/stats/genres - All genres with book counts

Key Files to Understand

1. backend/server.js - Express app setup, middleware, route registration
2. backend/config/db.js - PostgreSQL connection pool
3. backend/routes/books.js - All book-related endpoints
4. backend/routes/stats.js - Statistics queries
5. backend/services/bookApiService.js - Google Books API integration
6. frontend/src/services/api.js - Centralized API client
7. frontend/src/views/AddBookView.vue - Most complex component (search + form)
8. frontend/src/router/index.js - Route definitions
9. init-db.sql - Complete database schema
10. db.sh - Database management helper script

Database Helper Script

The ./db.sh script provides easy database management:

./db.sh start    # Start PostgreSQL container
./db.sh stop     # Stop container
./db.sh status   # Check if running
./db.sh psql     # Connect with psql
./db.sh logs     # View logs
./db.sh backup   # Create backup
./db.sh restore  # Restore from backup
./db.sh reset    # Fresh start (DELETES DATA)

Common Patterns

Backend Route Pattern

router.get('/endpoint', async (req, res) => {
  try {
    const { rows } = await pool.query('SELECT * FROM books');
    res.json(rows);
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Error message' });
  }
});

Frontend API Call Pattern

import { ref, onMounted } from 'vue'
import { bookApi } from '../services/api'

const data = ref([])
const loading = ref(true)
const error = ref(null)

const fetchData = async () => {
  loading.value = true
  try {
    const response = await bookApi.getAll()
    data.value = response.data
  } catch (err) {
    error.value = err.message
  } finally {
    loading.value = false
  }
}

onMounted(() => {
  fetchData()
})

PostgreSQL Array Queries

-- Insert array
INSERT INTO books (genres) VALUES (ARRAY['Fiction', 'Fantasy']);

-- Query array elements
SELECT * FROM books WHERE 'Fiction' = ANY(genres);

-- Expand array to rows
SELECT UNNEST(genres) as genre FROM books;

-- Count by genre
SELECT genre, COUNT(*) 
FROM books, UNNEST(genres) as genre 
GROUP BY genre;

Debugging Tips

1. Backend errors: Check terminal running npm run dev
2. Frontend errors: Check browser DevTools console (F12)
3. Database issues: Run ./db.sh logs or ./db.sh psql
4. CORS errors: Verify CORS_ORIGIN in backend .env matches frontend URL
5. API issues: Use curl or the ./test-api.sh script
6. Env var changes: Must restart dev servers (Ctrl+C, then npm run dev)

Testing

Manual Testing Flow

1. Start database: ./db.sh start
2. Start backend: cd backend && npm run dev
3. Start frontend: cd frontend && npm run dev
4. Open http://localhost:5173
5. Test: Add book → View in library → Edit → Delete

API Testing

# Health check
curl http://localhost:3000/api/health

# Search books
curl "http://localhost:3000/api/books/search?q=tolkien"

# Get all books
curl http://localhost:3000/api/books

# Run test script
./test-api.sh

Known Gotchas

1. Vite env vars: Changes require restart, not hot reload
2. Tailwind v4: Don't use old v3 config files or PostCSS setup
3. PostgreSQL arrays: Use ARRAY[] syntax, not {}
4. Date inputs: Browser locale affects display, but value is always ISO
5. CORS: Must match exact origin including protocol and port
6. Podman vs Docker: Commands are identical, just use podman instead of docker

Recent Changes

• Migrated to Tailwind CSS v4 with Vite plugin
• Converted all components to Composition API (<script setup>)
• Added reading date tracking (start_date, end_date)
• Added dashboard statistics with monthly chart
• Implemented book editing functionality
• Added ISBN detection utility
• Integrated Google Books API search

Future Enhancements (TODO)

• Re-read tracking (multiple reading sessions per book)
• Reading goals and progress tracking
• Book ratings and reviews
• Reading streaks
• Export data (CSV/JSON)
• Book recommendations
• Social features (share reading lists)

Git Workflow

• Single monorepo (not separate repos)
• Main branch: main
• Feature branches for new features
• Commit messages should mention affected area (Backend:, Frontend:, etc.)

Deployment Notes

• Monorepo structure optimized for Coolify
• Backend builds from /backend directory
• Frontend builds from /frontend directory
• Separate environment variables for each service
• Database can be external or Coolify-managed PostgreSQL

Quick Reference Commands

# Start everything
./db.sh start
cd backend && npm run dev     # Terminal 1
cd frontend && npm run dev    # Terminal 2

# Check status
./db.sh status
curl http://localhost:3000/api/health
curl http://localhost:3000/api/db-health

# Database access
./db.sh psql
# Inside psql: \dt (list tables), \d books (describe table), \q (quit)

# Reset database (CAUTION: deletes all data)
./db.sh reset

For AI Assistants:

• Always respect the established patterns (Composition API, Tailwind v4, PostgreSQL arrays)
• Check existing code before suggesting alternatives
• Test changes with curl for backend, browser for frontend
• Update relevant documentation when adding features
• Follow Vue 3 and modern JavaScript best practices