Educational Tutorial Series for Developers
🎓 Educational Tutorial Series for the Developer Community
Learn how to build conversational AI chatbots from scratch using Django, Django REST Framework, and Next.js. This hands-on tutorial introduces you to LangChain and LangGraph basics while building a real working chatbot.
This is a learning-focused repository designed to teach developers how to integrate AI into full-stack web applications. It's NOT a comprehensive enterprise solution - it's a clear, straightforward tutorial on building your first conversational chatbot.
What You'll Learn:
- Setting up Django + Django REST Framework for AI applications
- Building a modern frontend with Next.js
- Creating basic conversational chatbot functionality
- Introduction to LangChain fundamentals
- LangGraph basics for conversation flows
- Connecting Django backend with AI services
- Deploying a simple AI chatbot
Django, Celery, and Next.js run locally — only Postgres and Redis are Dockerized. This is the standard Django developer workflow: instant hot-reload,
pdbbreakpoints, real stack traces.
# Clone
git clone https://github.com/aparsoft/django-nextjs-chatbot.git
cd django-nextjs-chatbot
# Start Postgres + Redis
docker compose up -d
# Verify they're healthy
docker compose ps
# Should show chatbot-db (healthy) and chatbot-redis (healthy)This creates three databases automatically:
chatbot_db— Django modelslangchain_pgvector— pgvector embeddingslangchain_history— LangGraph checkpoints
cp .env.example .env
# Edit .env → set OPENAI_API_KEY=sk-proj-...cd backend
python3 -m venv venv
source venv/bin/activate # Linux/Mac
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver# Terminal 2 — Celery worker
cd backend && source venv/bin/activate
celery -A config worker --loglevel=info
# Terminal 3 — Celery beat (scheduler)
cd backend && source venv/bin/activate
celery -A config beat --loglevel=info# Terminal 4
cd frontend
npm install
npm run dev| Service | URL | Credentials |
|---|---|---|
| Frontend | http://localhost:3000 | — |
| Backend API | http://localhost:8000/api/v1/ | — |
| Django Admin | http://localhost:8000/chatbot-admin/ | (your superuser) |
| PostgreSQL | localhost:5434 | chatbot_user / chatbot_pass |
| Redis | localhost:6381 | — |
New to the project? Start here:
| Document | What It Covers |
|---|---|
| 📘 Intern Onboarding Guide | Day-by-day setup → first contribution |
| 🤝 Contributing Guide | Git workflow, PRs, code style |
| 🏗️ Model Architecture | 8 Django models, fatty model pattern |
| 📖 Django Lessons | 10 in-depth Django tutorials |
- Django 6+ + Django REST Framework — API development
- PostgreSQL 17 + pgvector — relational DB with vector similarity search
- Redis 7 — cache, Celery broker, Django Channels
- Celery + Celery Beat — background task processing & scheduling
- LangChain — LLM application framework
- LangGraph — stateful multi-step conversation flows with PostgresCheckpointer
- Next.js 16+ + React 19 — server-side rendered UI
- Tailwind CSS — utility-first styling
- Axios — HTTP client
- OpenAI GPT — chat completions, embeddings
- pgvector — vector similarity search for RAG
- LangGraph PostgresSaver — conversation checkpoint persistence
- Docker Compose — Postgres + Redis only (Django runs locally for hot-reload)
- pgvector/pgvector:pg17 — PostgreSQL image with pgvector pre-installed
┌─ YOUR MACHINE (local processes) ────────────────────────────┐
│ │
│ Terminal 1 Terminal 2 Terminal 3 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Django │ │ Celery │ │ Celery │ │
│ │ :8000 │ │ worker │ │ beat │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ │ │
│ Terminal 4 │ ┌──────────────┐ │
│ ┌──────────┐ │ │ OpenAI API │ │
│ │ Next.js │─────────────┤ │ (external) │ │
│ │ :3000 │ │ └──────────────┘ │
│ └──────────┘ │ │
└───────────────────────────┼─────────────────────────────────┘
│
┌─ DOCKER (infrastructure) ─┼──────────────────────────────────┐
│ ▼ │
│ ┌──────────────────┐ ┌───────────┐ │
│ │ PostgreSQL 17 │ │ Redis 7 │ │
│ │ + pgvector │ │ :6381 │ │
│ │ :5434 │ │ │ │
│ │ │ │ db0: cache│ │
│ │ • chatbot_db │ │ db1: broker │
│ │ • langchain_ │ │ db2: results │
│ │ pgvector │ │ │ │
│ │ • langchain_ │ │ │ │
│ │ history │ │ │ │
│ └──────────────────┘ └───────────┘ │
└──────────────────────────────────────────────────────────────┘
We use a single PostgreSQL instance with three separate databases:
| Database | Purpose | Used By |
|---|---|---|
chatbot_db |
Django models (users, sessions, preferences, tokens, feedback) | Django ORM |
langchain_pgvector |
Document embeddings + vector similarity search | LangChain PGVector |
langchain_history |
LangGraph checkpoints (conversation state, messages) | LangGraph PostgresSaver |
All three are created automatically by docker/init-db.sh on first startup.
We follow the "Fatty Models, Thin Viewsets" pattern — business logic lives in model methods, not in views.
CustomUser (accounts app)
│
├── ChatSession (1:N) ← Maps to LangGraph thread_id
│ ├── TokenUsage (1:N) ← Token costs per request
│ ├── MessageFeedback (1:N) ← User ratings on AI responses
│ └── UserDocument (1:N) ← RAG file uploads (pgvector refs)
│
├── UserPreference (1:1) ← AI settings & defaults
├── UserTool (1:N) ← Tool enable/disable + config
└── UserAPIKey (1:N) ← Encrypted provider API keys
SystemPromptTemplate (standalone) ← Reusable system prompts
Key principle: Django stores metadata (titles, settings, analytics). LangGraph stores actual messages. pgvector stores embeddings. No duplication!
📖 Full details: MODEL_ARCHITECTURE.md
This repository is the companion code for our beginner-friendly video tutorial series!
Part 1: Setup & Basics
- "Introduction: What We're Building"
- "Django + Next.js Setup from Scratch"
- "Your First API Call to OpenAI"
Part 2: Building the Chatbot
- "Creating the Django REST API"
- "Next.js Frontend Setup"
- "Connecting Frontend to Backend"
Part 3: Adding Intelligence
- "Introduction to LangChain"
- "Basic Conversation Memory"
- "Introduction to LangGraph"
Part 4: Deployment
- "Docker Basics for Beginners"
- "Deploying Your First Chatbot"
We welcome contributions from developers at all levels!
| Resource | Link |
|---|---|
| 📘 Intern Onboarding | docs/INTERN_ONBOARDING.md |
| 🤝 Contributing Guide | docs/CONTRIBUTING.md |
| 🏗️ Model Architecture | backend/apps/chatbot/models/MODEL_ARCHITECTURE.md |
| 📖 Django Lessons (10) | backend/docs/lessons/django/ |
Not sure where to start? Check the Contributing Guide for the complete Git workflow and first-task suggestions!
- YouTube: @aparsoft-ai
- LinkedIn: /company/aparsoft
- GitHub Issues: Report bugs here
- Website: aparsoft.com
Copyright © 2024 Aparsoft Private Limited. All rights reserved.
This code is provided for educational purposes. Feel free to learn from it, modify it, and use it in your own projects!
Built with ❤️ by the Aparsoft Team in Bengaluru, India