🎓 AGEN — AI English Learning Agent

Personalized English learning platform for Vietnamese learners, powered by Gemini AI.

Stack: FastAPI · Next.js 16 · PostgreSQL · SQLite (dev) · Zustand · Tailwind-like CSS

---

🏗️ Project Structure

AI_English_Learning_Agent/
├── agen-backend/     # FastAPI backend
└── agen-web/         # Next.js 16 frontend

---

🚀 Quick Start (Local Development)

Backend

cd agen-backend
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # Mac/Linux

pip install -r requirements.txt
cp .env.example .env           # Fill in your API keys
uvicorn main:app --reload --port 8000

API docs: http://localhost:8000/docs

Frontend

cd agen-web
npm install
# Create .env.local:
echo "NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1" > .env.local
npm run dev

App: http://localhost:3000

---

☁️ Production Deployment

Architecture

[User] → [Vercel CDN] → [Next.js Frontend]
                              ↓ API calls
                    [Render.com Web Service]
                         [FastAPI Backend]
                              ↓
                    [Render.com PostgreSQL]

---

Step 1 — Deploy Backend to Render.com

1. Push code to GitHub (ensure agen-backend/ is in your repo)

2. Create a Render account at https://render.com

3. New → Blueprint → connect your GitHub repo

   • Render will auto-detect agen-backend/render.yaml
   • This creates: Web Service + PostgreSQL database automatically

4. Set secret environment variables in Render Dashboard:

   • GEMINI_API_KEY → set this secret directly in Render Environment Variables
   • OPENAI_API_KEY → your OpenAI key (optional)
   • SECRET_KEY → auto-generated by Render (or set your own)

5. First deploy will:

   • Build Docker image
   • Run alembic upgrade head (create all tables)
   • Start uvicorn server

6. Note your backend URL: https://agen-api.onrender.com

⚠️ Free tier sleeps after 15 min inactivity — first request takes ~30s to wake up. Upgrade to Starter ($7/mo) for always-on.

---

Step 2 — Deploy Frontend to Vercel

1. Create a Vercel account at https://vercel.com

2. New Project → Import your GitHub repo

   • Set Root Directory to agen-web
   • Framework: Next.js (auto-detected)

3. Set environment variable in Vercel Dashboard:

   • NEXT_PUBLIC_API_URL = https://agen-api.onrender.com/api/v1

4. Click Deploy — Vercel builds and deploys automatically.

5. Update CORS in Render: set ALLOWED_ORIGINS to your Vercel URL

   • e.g. https://agen-web.vercel.app

---

Step 3 — Verify Production

# Health check
curl https://agen-api.onrender.com/health

# Register test user
curl -X POST https://agen-api.onrender.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"Test1234","full_name":"Test","display_name":"Test"}'

---

🧪 Pilot Setup (chạy thử nghiệm nội bộ trên máy tính)

Phần này hướng dẫn dựng một bản pilot chạy local trên giao diện máy tính.

1. Backend

cd agen-backend
python -m venv venv
venv\Scripts\activate                 # Windows
pip install -r requirements.txt
copy .env.example .env                # Windows (hoặc: cp .env.example .env)

Người vận hành pilot mở agen-backend/.env và điền tối thiểu:

APP_ENV=development
SECRET_KEY=<chạy: python -c "import secrets; print(secrets.token_hex(32))">
DATABASE_URL=sqlite:///./agen_dev.db
ALLOWED_ORIGINS=http://localhost:3000
GEMINI_API_KEY=<khóa Gemini do người vận hành quản lý>
ADMIN_EMAILS=<email quản trị của bạn>   # để truy cập trang /admin
FREE_DAILY_LESSON_LIMIT=3               # bài/ngày cho gói free (0 = không giới hạn)

Khởi động server (KHÔNG dùng --reload khi pilot để tránh vòng lặp reload):

python -m uvicorn main:app --host 0.0.0.0 --port 8000

2. Frontend

cd agen-web
npm install
echo NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1 > .env.local
npm run dev

Mở app tại http://localhost:3000

3. Sinh sẵn nội dung bài học (khuyến nghị — để học viên không phải chờ AI)

AGEN sinh nội dung bài học bằng AI. Nếu sinh sẵn + duyệt trước, học viên sẽ nhận bài tức thì (không tốn quota, nội dung ổn định). Chạy CLI:

cd agen-backend
# Sinh + tự duyệt toàn bộ nội dung cấp A1 (mỗi bài = 1 lượt gọi AI):
python scripts/pregenerate_content.py --level A1 --auto-approve

# Có thể làm tiếp A2, B1 (tùy quota AI của bạn):
python scripts/pregenerate_content.py --level A2 --auto-approve
python scripts/pregenerate_content.py --level B1 --auto-approve

⚠️ Quota AI: Gemini free tier giới hạn ~20 lượt/ngày. Sinh cả một cấp độ (24 bài) sẽ dùng hết quota trong ngày. Dùng khóa trả phí để sinh toàn bộ một lần, hoặc chia nhiều ngày. Bài chưa sinh sẵn vẫn hoạt động — hệ thống tự sinh live khi học viên mở.

Nếu muốn review thủ công trước khi phát hành: bỏ --auto-approve (nội dung ở trạng thái draft), rồi vào /admin → tab Kho nội dung để duyệt từng bài.

4. Đăng nhập quản trị

Trang /admin (giám sát chất lượng AI + quản lý kho nội dung) chỉ mở cho email nằm trong ADMIN_EMAILS. Đăng ký một tài khoản bằng đúng email đó rồi truy cập /admin.

5. Chạy test tự động

cd agen-backend
pytest -q

---

🔑 Environment Variables Reference

Backend (agen-backend/.env)

Variable	Required	Description
APP_ENV	Yes	development or production
SECRET_KEY	Yes	JWT signing key — use python -c "import secrets; print(secrets.token_hex(32))"
DATABASE_URL	Yes	PostgreSQL or SQLite URL
ALLOWED_ORIGINS	Yes	Comma-separated frontend URLs
GEMINI_API_KEY	Yes*	Google Gemini API key
OPENAI_API_KEY	No	OpenAI API key (alternative to Gemini)
ADMIN_EMAILS	No	Comma-separated emails cho phép truy cập /admin (rỗng = không ai)
FREE_DAILY_LESSON_LIMIT	No	Số bài/ngày cho gói free (mặc định 3; 0 = không giới hạn)
ACCESS_TOKEN_EXPIRE_MINUTES	No	Default: 1440 (24h)

*At least one AI key is required.

Frontend (agen-web/.env.local)

Variable	Required	Description
NEXT_PUBLIC_API_URL	Yes	Backend API base URL

---

🗄️ Database Migrations

# Run on new environment (production)
cd agen-backend
alembic upgrade head

# Create new migration after model changes
alembic revision --autogenerate -m "describe_your_change"

# Check current migration status
alembic current

---

🐳 Docker (Optional Local Stack)

cd agen-backend

# Build image
docker build -t agen-backend .

# Run with env vars
docker run -p 8000:8000 \
  -e DATABASE_URL="sqlite:///./agen_dev.db" \
  -e SECRET_KEY="your-dev-key" \
  -e GEMINI_API_KEY="your-key" \
  -e ALLOWED_ORIGINS="http://localhost:3000" \
  agen-backend

---

🧰 Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript, Zustand
Backend	FastAPI, SQLAlchemy 2, Pydantic v2
Database	PostgreSQL (prod), SQLite (dev)
AI	Google Gemini 3.6 Flash / OpenAI GPT-4o-mini
Auth	JWT (python-jose), bcrypt
Migrations	Alembic
Deployment	Render.com (backend), Vercel (frontend)
Rate Limiting	slowapi

---

📖 API Documentation

Available at /docs (Swagger UI) — only in APP_ENV=development.

Disabled in production for security.