Agentic Chat — End-to-End Educational Project for Students

English edition. The Arabic edition is the primary one: see README.md in the repository root. The tutorials portal at / links to this tutorial at /ai-chat/; its English edition lives at /en/ai-chat/. Every lesson exists in both languages.

What You Will Build

A full-stack chat application where you can talk to an AI assistant. You will build:

  • A Python Flask backend with SQLite that stores chat messages and calls an LLM (OpenAI, Anthropic, etc.)
  • A React Native (Expo) mobile app with a chat interface
  • An agentic AI that can use tools (calculator, search) to answer questions

Learning Objectives

By the end of this project you will know how to:

  1. Set up a Python Flask web server with database storage
  2. Build REST API endpoints (GET, POST, DELETE)
  3. Call external AI APIs (OpenAI, Anthropic, Google, etc.)
  4. Build a mobile chat app with React Native / Expo
  5. Make the AI "agentic" — give it tools to reason and act
  6. Add RAG (Retrieval-Augmented Generation) to answer from a knowledge base
  7. Write automated tests for all components
  8. Lint and format code with ruff
  9. Add monitoring (health checks, metrics, structured logging)
  10. Set up CI/CD for automated testing and deployment
  11. Deploy your app to production

Prerequisites

No prior experience with Flask, React Native, or AI is assumed. You should:

  • Be comfortable using a computer (installing software, using a browser)
  • Have basic programming knowledge (any language)

If you need to learn the fundamentals first, start with the prerequisites section.

How to Navigate This Project

prerequisites/      → Terminal, git, Python, TypeScript, Arabic keyboard — start here if you're new
concepts/           → What is an API? How to read errors? LLM comparison?
cheatsheets/        → Quick reference cards for Flask, SQLAlchemy, React Native, OpenAI
deployment/         → Deploy to production (Hugging Face Spaces, CI/CD, PostgreSQL migration)
backend/            → Build the Python Flask chat API (6 steps + challenges + tests)
mobile/             → Build the React Native chat app (5 steps + challenges)
advanced/agentic/   → Make your chat bot agentic (5 steps + challenges + tests)
advanced/rag/       → Add RAG with pgvector, embeddings, and knowledge base (5 steps + tests)
concepts/           → Also covers containers, Docker, and development principles
glossary.md         → All technical terms defined
final-runbook.md    → Run everything end-to-end

Suggested Reading Order

  1. prerequisites/00-system-setup.md — Get your computer ready
  2. prerequisites/01-terminal.md through 05-typescript-scripting.md, plus 06-arabic-keyboard.md
  3. concepts/01-what-is-an-api.md
  4. backend/step-01-setup.md through step-06-cors.md
  5. mobile/step-01-setup.md through step-05-polish.md
  6. concepts/05-llm-comparison.md — Explore other AI models
  7. final-runbook.md — Run the full project
  8. advanced/agentic/ — Make it agentic
  9. advanced/rag/ — Add RAG knowledge base
  10. deployment/ — Deploy to production (includes CI/CD)

Tech Stack

Layer Technology
Backend framework Flask (Python)
Database SQLite (dev), PostgreSQL (prod)
AI models OpenAI GPT-4o-mini (default), swap to Anthropic, Google, DeepSeek, Llama, Mistral
Mobile app React Native with Expo (TypeScript)
Deployment Hugging Face Spaces (backend), EAS Build (mobile)
Testing pytest, ruff (linting)
Monitoring Health endpoint, structured logging, request metrics
CI/CD GitHub Actions (auto-test + auto-deploy)

Project Structure

agentic_chat_tutorial/
├── README.md              ← Arabic edition (primary)
├── TRANSLATING.md         ← translation guide + terminology
├── en/                    ← English edition (mirrors every lesson path)
├── prerequisites/         ← lessons (10 files)
├── concepts/              ← (6 files)
├── cheatsheets/           ← (4 files)
├── backend/               ← tutorial + app/ (Flask code) + tests/
├── mobile/                ← tutorial + App.tsx
├── advanced/              ← agentic/ + rag/ + tests + Docker compose
├── deployment/            ← (6 files)
├── website/               ← bilingual static-site generator + templates
├── final-runbook.md
├── glossary.md
└── .github/workflows/     ← CI + CD workflows

Why Arabic?

This repository is Arabic-first: Arabic-speaking learners should not have to learn a new language before learning to code. The lessons, explanations, and error walkthroughs are in Arabic, while code stays in English because that is what the tools, libraries, and error messages use. English readers get the same content under en/. Translations and corrections are welcome — see TRANSLATING.md.

License

Creative Commons Attribution 4.0 (CC BY 4.0)