Knowledge Base

knowledge_base is a production-like Django pet project for a personal knowledge base: notes, study summaries, technical guides, bug fixes, and ideas. The scope stays intentionally tight: a clean core, clear business rules, reusable query logic, and a complete HTML + API baseline without premature complexity.

Screenshots

Home

Note detail

Tag page

Features

• Public and private notes with author-only editing.
• Search across title, content, and tags.
• Tags with slug generation and case-insensitive uniqueness.
• Comments with soft delete.
• Voting with update-in-place behavior.
• Favorites for authenticated users.
• HTML interface and DRF API with JWT authentication.
• Shared selectors/query helpers reused across HTML and API.
• CI with tests, lint, format check, and coverage report.

Architecture decisions

• core/selectors.py is the source of truth for visibility rules and shared note query logic.
• comments_count and vote_score are annotated at queryset level to avoid N+1 queries in lists and detail pages.
• vote_score uses a Subquery, so it is not corrupted by JOIN duplication with comments.
• Tag visibility is protected: if a user cannot see any note for a tag, both HTML and API return 404.
• The project keeps a single settings.py and avoids over-engineering in the early stage.

Tech stack

• Python 3.13
• Django 5.1
• Django REST Framework
• Simple JWT
• SQLite
• Pytest
• Ruff
• Celery (basic eager/dev setup for cache warmup task)

Quick start

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\python -m pip install --upgrade pip
.\.venv\Scripts\python -m pip install -r requirements-dev.txt
.\.venv\Scripts\python manage.py migrate
.\.venv\Scripts\python manage.py createsuperuser
.\.venv\Scripts\python manage.py runserver

Generic

python -m venv .venv
python -m pip install --upgrade pip
pip install -r requirements-dev.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Open:

• http://127.0.0.1:8000/
• http://127.0.0.1:8000/admin/

Project structure

• knowledge_base/ - settings, root URLs, ASGI/WSGI, Celery bootstrap
• accounts/ - signup/login, profile model, profile page
• notes/ - note model, HTML CRUD, search, privacy rules
• tags/ - tag model and tag page
• comments/ - comments and soft delete logic
• votes/ - voting model and vote update logic
• favorites/ - favorites page and add/remove behavior
• api/ - serializers, permissions, pagination, REST endpoints
• core/ - selectors, services, constants, reusable tasks
• templates/ - shared and app HTML templates
• docs/screenshots/ - README screenshots

HTML routes

• GET /
• GET /notes/
• GET|POST /notes/create/
• GET|POST /notes/<slug>/
• GET|POST /notes/<slug>/edit/
• GET|POST /notes/<slug>/delete/
• GET /tags/<slug>/
• GET /favorites/
• GET /profile/<username>/
• GET|POST /accounts/signup/
• GET|POST /accounts/login/

API endpoints

Auth

• POST /api/auth/token/
• POST /api/auth/token/refresh/

Notes

• GET /api/notes/
• POST /api/notes/
• GET /api/notes/<slug>/
• PATCH /api/notes/<slug>/
• DELETE /api/notes/<slug>/

Comments

• GET /api/notes/<slug>/comments/
• POST /api/notes/<slug>/comments/

Votes

• POST /api/notes/<slug>/vote/

Favorites

• POST /api/notes/<slug>/favorite/
• DELETE /api/notes/<slug>/favorite/
• GET /api/favorites/

Tags

• GET /api/tags/
• GET /api/tags/<slug>/notes/

API examples

Get JWT pair:

curl -X POST http://127.0.0.1:8000/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

Create a note:

curl -X POST http://127.0.0.1:8000/api/notes/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Django tips","content":"Use select_related.","is_public":true,"tag_names":["django","orm"]}'

Vote for a note:

curl -X POST http://127.0.0.1:8000/api/notes/django-tips/vote/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"value":1}'

Quality gates

Run tests:

pytest -q

Run coverage:

pytest --cov=. --cov-report=term-missing

Run lint:

ruff check .
ruff format --check .

Verification

The project was re-checked in a fresh clone with a clean virtual environment:

• dependency installation from requirements-dev.txt
• python manage.py migrate
• python manage.py check
• pytest -q
• pytest --cov=. --cov-report=term-missing
• ruff check .
• ruff format --check .

Current local result:

• tests: 24 passed
• coverage: 92%

Background task

The project includes core.tasks.warm_public_notes_cache, a small Celery task that warms the cached first page of public notes. In development and tests, Celery runs eagerly. For a real deployment, the broker/backend should be switched from in-memory to Redis or another persistent backend.