The Project & The Method

You've spent this module learning Python web frameworks and how they connect to a React frontend. A weekend project is where that knowledge becomes muscle memory. Rather than following keystrokes blindly, you'll build BookTracker using a discipline that scales to any project: George Polya's four-step method from his 1945 classic How to Solve It.

💡 Why a method, not just a tutorial? Tutorials teach you to reproduce one app. A method teaches you to build the next app — the one with no tutorial. Polya's four steps map almost perfectly onto professional software work, so practicing them here pays dividends for your whole career.

Notice that Polya's loop is a cycle, not a straight line. Real builds circle back: something you learn while executing sends you back to re-plan, and the review step feeds the next iteration. That's expected and healthy — this lesson is structured to make the loop visible.

The Milestone Map

Big projects fail when they're one giant undivided task. We'll slice the weekend into five milestones, each with a concrete definition of done. Aim to reach a working state at the end of each — never leave the app broken overnight.

Milestone 0 — Understand the Problem

Before a single line of code, get crisp on what and for whom. Cheap to change now, expensive to change later.

Ask the right questions

• What problem? Readers lack a simple place to track what they own, what they're reading, and what they thought of it.
• Who's the user? A single book enthusiast managing their own shelf — so every record is scoped to one owner.
• What's core? Add/edit/delete books, track status, and keep it private per user.
• What are the constraints? One weekend, Python + React, must work on a phone screen.
• What does success look like? A logged-in user can manage their shelf end to end without errors.

Write user stories

User stories keep you honest about building features people asked for, in the form "As a <user>, I want <goal> so that <reason>."

1. As a reader, I want to register and log in so my shelf is private to me.
2. As a reader, I want to add a book so I can track what I own.
3. As a reader, I want to set a book's status (to-read / reading / completed)
   so I can see my progress at a glance.
4. As a reader, I want to filter my shelf by status so I can find books fast.
5. As a reader, I want to edit or delete a book so I can fix mistakes.
6. (Nice-to-have) As a reader, I want notes and a review per book
   so I remember my thoughts.
7. (Nice-to-have) As a reader, I want simple stats so I can see my habits.

Model the domain

Sketch how the "things" in the app relate. A user owns many books; each book can carry reading sessions, notes, and one review.

Milestone 1 — Devise a Plan

With the problem understood, decide how you'll build it. Planning on paper for an hour saves many hours of thrashing in code.

The stack

System architecture

Two apps talk over HTTP/JSON. The React SPA never touches the database directly — it always goes through the API.

The API contract

Agree the endpoints up front so backend and frontend can be built against the same "contract."

# Auth
POST   /api/auth/register/         Create an account
POST   /api/auth/token/            Log in → { access, refresh }
POST   /api/auth/token/refresh/    Get a fresh access token

# Books (all owner-scoped, all require auth)
GET    /api/books/                 List my books  (?status=reading to filter)
POST   /api/books/                 Add a book
GET    /api/books/{id}/            One book
PUT    /api/books/{id}/            Update a book
DELETE /api/books/{id}/            Delete a book

# Nice-to-have
GET    /api/stats/reading/         Reading summary counts

The component tree

Milestone 2 — Build the Backend

Build the API first and prove it works with curl before touching React. A trustworthy backend makes frontend work fast; a shaky one makes it miserable.

Step 1 — Project setup

python -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate

pip install django djangorestframework djangorestframework-simplejwt django-cors-headers

django-admin startproject booktracker
cd booktracker
python manage.py startapp books
python manage.py startapp users

Step 2 — Configure settings

# booktracker/settings.py
from datetime import timedelta

INSTALLED_APPS = [
    # ...Django defaults...
    "rest_framework",
    "corsheaders",
    "books",
    "users",
]

MIDDLEWARE = [
    "corsheaders.middleware.CorsMiddleware",   # must be high in the list
    # ...other middleware...
]

# Let the Vite dev server talk to us during development
CORS_ALLOWED_ORIGINS = ["http://localhost:5173"]

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticated",
    ],
}

SIMPLE_JWT = {
    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=60),
    "REFRESH_TOKEN_LIFETIME": timedelta(days=14),
}

AUTH_USER_MODEL = "users.User"   # set this BEFORE the first migration

Step 3 — Models

# users/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    bio = models.TextField(blank=True)

# books/models.py
from django.conf import settings
from django.core.validators import MinValueValidator, MaxValueValidator
from django.db import models

class Book(models.Model):
    class Status(models.TextChoices):
        TO_READ = "to_read", "To Read"
        READING = "reading", "Currently Reading"
        COMPLETED = "completed", "Completed"
        DNF = "dnf", "Did Not Finish"

    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="books"
    )
    title = models.CharField(max_length=255)
    author = models.CharField(max_length=255)
    isbn = models.CharField(max_length=13, blank=True)
    pages = models.PositiveIntegerField(null=True, blank=True)
    status = models.CharField(
        max_length=20, choices=Status.choices, default=Status.TO_READ
    )
    date_added = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["-date_added"]

    def __str__(self):
        return f"{self.title} by {self.author}"

class ReadingSession(models.Model):
    book = models.ForeignKey(Book, on_delete=models.CASCADE, related_name="sessions")
    start_date = models.DateField()
    end_date = models.DateField(null=True, blank=True)
    pages_read = models.PositiveIntegerField(default=0)

class Review(models.Model):
    book = models.OneToOneField(Book, on_delete=models.CASCADE, related_name="review")
    rating = models.PositiveSmallIntegerField(
        validators=[MinValueValidator(1), MaxValueValidator(5)]
    )
    content = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

Step 4 — Serializers

# books/serializers.py
from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ["id", "title", "author", "isbn", "pages",
                  "status", "date_added"]
        read_only_fields = ["id", "date_added"]

# users/serializers.py
from rest_framework import serializers
from django.contrib.auth import get_user_model

User = get_user_model()

class RegisterSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True, min_length=8)

    class Meta:
        model = User
        fields = ["username", "email", "password"]

    def create(self, validated_data):
        # create_user hashes the password — never store it in plain text
        return User.objects.create_user(**validated_data)

Step 5 — Views & permissions

# books/views.py
from rest_framework import viewsets, permissions
from .models import Book
from .serializers import BookSerializer

class IsOwner(permissions.BasePermission):
    """Object-level: only the owner may touch their book."""
    def has_object_permission(self, request, view, obj):
        return obj.owner == request.user

class BookViewSet(viewsets.ModelViewSet):
    serializer_class = BookSerializer
    permission_classes = [permissions.IsAuthenticated, IsOwner]

    def get_queryset(self):
        # Never leak another user's books
        qs = Book.objects.filter(owner=self.request.user)
        status = self.request.query_params.get("status")
        return qs.filter(status=status) if status else qs

    def perform_create(self, serializer):
        serializer.save(owner=self.request.user)   # stamp the owner server-side

Step 6 — URLs

# users/urls.py
from django.urls import path
from rest_framework_simplejwt.views import TokenObtainPairView, TokenRefreshView
from .views import RegisterView

urlpatterns = [
    path("register/", RegisterView.as_view(), name="register"),
    path("token/", TokenObtainPairView.as_view(), name="token"),
    path("token/refresh/", TokenRefreshView.as_view(), name="token_refresh"),
]

# booktracker/urls.py
from django.contrib import admin
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from books.views import BookViewSet

router = DefaultRouter()
router.register(r"books", BookViewSet, basename="book")

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/auth/", include("users.urls")),
    path("api/", include(router.urls)),
]

Step 7 — Migrate & smoke-test

python manage.py makemigrations
python manage.py migrate
python manage.py runserver

# In another terminal — register, log in, then create a book:
curl -X POST http://localhost:8000/api/auth/register/ \
  -H "Content-Type: application/json" \
  -d '{"username":"ray","email":"ray@example.com","password":"supersecret"}'

curl -X POST http://localhost:8000/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"ray","password":"supersecret"}'
# → copy the "access" token from the response

curl http://localhost:8000/api/books/ \
  -H "Authorization: Bearer PASTE_ACCESS_TOKEN_HERE"

[]

Milestone 3 — Build the Frontend

With a proven API, the React work is mostly wiring: hold the token, attach it to requests, and render the JSON.

Step 1 — Scaffold with Vite

npm create vite@latest booktracker-frontend -- --template react
cd booktracker-frontend
npm install
npm install axios react-router-dom
npm run dev            # serves at http://localhost:5173

Step 2 — An axios client that carries the token

One interceptor attaches the access token to every request; another transparently refreshes it on a 401 so users aren't kicked out mid-session.

// src/api/client.js
import axios from "axios";

const apiClient = axios.create({ baseURL: "http://localhost:8000/api" });

apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem("token");
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    const original = error.config;
    if (error.response?.status === 401 && !original._retry) {
      original._retry = true;
      const refresh = localStorage.getItem("refreshToken");
      if (!refresh) return Promise.reject(error);
      try {
        const { data } = await axios.post(
          "http://localhost:8000/api/auth/token/refresh/",
          { refresh }
        );
        localStorage.setItem("token", data.access);
        original.headers.Authorization = `Bearer ${data.access}`;
        return apiClient(original);        // replay the original request
      } catch (refreshError) {
        localStorage.removeItem("token");
        localStorage.removeItem("refreshToken");
        window.location.href = "/login";
        return Promise.reject(refreshError);
      }
    }
    return Promise.reject(error);
  }
);

export default apiClient;

Step 3 — An auth context

Context makes "who is logged in?" available anywhere without prop-drilling.

// src/context/AuthContext.jsx
import { createContext, useContext, useState } from "react";
import apiClient from "../api/client";

const AuthContext = createContext(null);

export function AuthProvider({ children }) {
  const [user, setUser] = useState(() =>
    localStorage.getItem("token") ? { loggedIn: true } : null
  );

  async function login(username, password) {
    const { data } = await apiClient.post("/auth/token/", { username, password });
    localStorage.setItem("token", data.access);
    localStorage.setItem("refreshToken", data.refresh);
    setUser({ loggedIn: true });
  }

  function logout() {
    localStorage.removeItem("token");
    localStorage.removeItem("refreshToken");
    setUser(null);
  }

  return (
    
      {children}
    
  );
}

export const useAuth = () => useContext(AuthContext);

Step 4 — Protected routes

// src/routes/ProtectedRoute.jsx
import { Navigate } from "react-router-dom";
import { useAuth } from "../context/AuthContext";

export default function ProtectedRoute({ children }) {
  const { user } = useAuth();
  return user ? children : ;
}

// src/App.jsx
import { BrowserRouter, Routes, Route } from "react-router-dom";
import { AuthProvider } from "./context/AuthContext";
import ProtectedRoute from "./routes/ProtectedRoute";
import Login from "./pages/Login";
import BookList from "./pages/BookList";

export default function App() {
  return (
    
      
        
          } />
          
                
              
            }
          />
        
      
    
  );
}

Step 5 — The book list with a status filter

This one component demonstrates the whole loop: fetch on mount, re-fetch when the filter changes, and render the JSON.

// src/pages/BookList.jsx
import { useEffect, useState } from "react";
import apiClient from "../api/client";

const STATUSES = ["", "to_read", "reading", "completed"];

export default function BookList() {
  const [books, setBooks] = useState([]);
  const [filter, setFilter] = useState("");
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    setLoading(true);
    apiClient
      .get("/books/", { params: filter ? { status: filter } : {} })
      .then((res) => setBooks(res.data))
      .catch((err) => console.error("Failed to load books", err))
      .finally(() => setLoading(false));
  }, [filter]);

  if (loading) return 
Loading your shelf…
;

  return (
    

      
My Shelf
       setFilter(e.target.value)}>
        {STATUSES.map((s) => (
          {s || "All"}
        ))}
      

      {books.length === 0 ? (
        
No books yet — add your first one!
      ) : (
        

          {books.map((book) => (
            

              {book.title} by {book.author} — {book.status}
            
          ))}
        
      )}
    
  );
}

Milestone 4 — Review & Extend

Polya's fourth step — "looking back" — is the one beginners skip and professionals treasure. Reviewing turns a working app into a good app and a finished weekend into durable learning.

Test the real journeys

Click through the app as a user, not a coder. Walk each user story end to end:

• Register → log in → land on the shelf
• Add a book → it appears immediately and after a reload
• Change a status → the filter reflects it
• Delete a book → it's gone and stays gone
• Log out → protected routes bounce you to login
• Wait for the access token to expire → the refresh flow keeps you signed in
• Shrink the window to phone width → the layout still works

Reflect with Polya's four questions

Sensible extensions (pick one)

Only after the must-haves are solid. Each is a fresh mini-loop of understand → plan → execute → review:

• Reading sessions & notes — the nice-to-have models you already sketched.
• Stats page — wire up /api/stats/reading/ and show counts by status.
• ISBN lookup — autofill title/author from the Open Library API.
• Pagination — turn on DRF pagination once your shelf grows.
• Automated tests — a few DRF APITestCase tests for the book endpoints.
• Deploy — Postgres + a host (Railway/Render for the API, Netlify/Vercel for the SPA).

Document it

A README.md is the difference between a project you can show and one you can't. Include: what it does, the stack, how to run backend and frontend locally, and a screenshot or two.

Completion Checklist

Tick these off as you go. If you can check every must-have box, you've shipped a real full-stack app.

What Good Looks Like

"It runs" is the floor, not the bar. Here's how to tell a rushed weekend hack from a build you'd proudly link on your résumé.

💡 The professional habit: a senior developer isn't someone who never has to review and fix their work — it's someone who always does. The "what good looks like" bar is just the review step made explicit.

Summary & Quiz

📚 Further Reading

• George Polya — "How to Solve It"
• Django REST Framework documentation
• SimpleJWT — JWT auth for DRF
• React — official learn guide
• Vite — getting started

🚀 What's Next?

You've built a full-stack app in Python and React and, more importantly, practiced a method you can reuse forever. Next we cross into the PHP world and unpack how the Laravel framework is architected — you'll see the same layers (routing, controllers, ORM, auth) wearing different clothes.