📚 Ketab Yar — Django Bookstore Project

A full-stack, Persian-language Django web app for listing, browsing, and reviewing books.

Overview

Ketab Yar (کتاب یار — Persian for "Book Companion") is a full-stack Django web app for listing, browsing, and reviewing books. Authenticated users publish their own listings with a cover image and price; anyone can browse the catalog, open a book's details, and leave a comment with a recommend / don't-recommend rating. The core browsing, listing, and account pages are localized with a right-to-left (RTL) Persian interface, with prices shown in Toman — this documentation is in English so the project stays accessible to a wider audience.

Features

• Custom user accounts — extends Django's AbstractUser with an age field; full signup, login, logout, and password change/reset flow.
• Book catalog — paginated list view (4 per page) with cover thumbnails, author, and a truncated description.
• Full CRUD for books — logged-in users can create, update, and delete listings; editing/deleting is restricted to the original owner via UserPassesTestMixin.
• Comments & recommendations — readers can comment on any book and mark whether they recommend it, with an is_active flag for moderation.
• Cover image uploads — handled through Django's ImageField, served from /media/.
• Persian (Farsi) RTL interface — the catalog, detail, forms, and login pages are localized in Persian with right-to-left layout; prices are shown in Toman (تومان).
• Django admin — customized to manage users (with the extra age field), books, and comments.
• Automated tests — coverage for the signup flow and home page.

Tech Stack

Category	Technology
Language	Python 3.12+
Framework	Django 6.0
Frontend	Django Templates, Bootstrap 5.3, django-crispy-forms (crispy-bootstrap5)
Database	SQLite (development)
Image handling	Pillow
Auth	django.contrib.auth with a custom user model

Project Structure

django_bookstore_project/
├── accounts/            # Custom user model, signup view & forms
│   ├── models.py        # CustomUser (extends AbstractUser)
│   ├── forms.py         # Signup / admin change forms
│   └── views.py         # SignUpView
├── books/                # Core app: listings, comments, CRUD
│   ├── models.py         # Book, Comment
│   ├── views.py          # List / Detail / Create / Update / Delete views
│   ├── templatetags/     # Custom template tags (scaffolded, not yet used)
│   └── templates/books/
├── pages/                 # Static pages (home)
├── config/                # Project settings, URLs, WSGI/ASGI
├── templates/             # Base template + auth (registration) templates
├── static/                # CSS, fonts, icons
├── media/covers/          # Uploaded book cover images
└── manage.py

Getting Started

Prerequisites

• Python 3.12+
• pip and venv
• git

Installation

The repository doesn't yet ship a requirements.txt, so install the packages directly:

git clone https://github.com/sahebi-code/django_bookstore_project.git
cd django_bookstore_project

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

pip install "Django>=6.0" django-crispy-forms crispy-bootstrap5 Pillow

The repo includes a pre-populated db.sqlite3 (a handful of sample books, comments, and users), so you can run the server right away:

python manage.py runserver

Then visit http://127.0.0.1:8000/. If you'd rather start from a clean database, delete db.sqlite3 first and run python manage.py migrate (and optionally python manage.py createsuperuser for admin access) before starting the server.

Usage

1. Sign up at /accounts/signup/, or log in if you already have an account.
2. Browse the catalog at /books/ — no login required.
3. Open a book to read the full description, price, and existing comments (login required).
4. Leave a comment and mark whether you recommend the book.
5. Add your own book via "اضافه کردن کتاب" in the navbar — requires a title, author, description, price, and optional cover image.
6. Edit or delete a listing you created from its detail page.
7. Manage everything — users, books, comments — from /admin/.

Routes

Method	Path	Name	Description	Access
GET	/	home	Landing page	Public
GET/POST	/accounts/signup/	signup	Register a new account	Public
GET/POST	/accounts/login/	login	Log in	Public
POST	/accounts/logout/	logout	Log out	Authenticated
GET/POST	/accounts/password_change/	password_change	Change password	Authenticated
GET/POST	/accounts/password_reset/	password_reset	Request a password reset email	Public
GET	/books/	book_list	Paginated catalog of all books	Public
GET/POST	/books/<id>/	book_detail	Book details, comments & comment form	Authenticated
GET/POST	/books/new/	book_create	Add a new book	Authenticated
GET/POST	/books/<id>/edit/	book_update	Edit a book	Owner only
GET/POST	/books/<id>/delete/	book_delete	Delete a book (with confirmation)	Owner only
—	/admin/	—	Django admin panel	Staff

Running Tests

python manage.py test

Current coverage: the accounts app (signup flow) and pages app (home view) ship with test suites. The books app — which holds the core listing, comment, and permission logic — doesn't have tests yet; that's a good next addition.

Roadmap

• Add a requirements.txt (or pyproject.toml) for reproducible installs
• Move SECRET_KEY and DEBUG out of source control via environment variables (e.g. django-environ + .env)
• Add test coverage for the books app
• Increase Book.price precision — it's currently capped at 999.99, which is too small for realistic Toman-denominated book prices
• Decide on a consistent access rule for browsing: book_list is public but book_detail currently requires login
• Migrate the hardcoded Persian UI strings to Django's i18n framework ({% trans %} / .po files) to support real multi-language switching
• Add search and category filtering to the book catalog
• Swap SQLite for PostgreSQL and configure static/media storage for a production deployment

Author

Mohammad — @sahebi-code

License

This repository doesn't currently include a license file, so all rights are reserved by default.