Dental Chatbot - Sistema de Agendamento com IA
OthmanMohammad/dental-chatbot
Chatbot conversacional para agendamento automático de consultas dentárias
Ver no GitHubSistema completo de agendamento de consultas odontológicas usando Claude AI e LangChain. Arquitetura em três camadas (Next.js frontend, Node.js backend, FastAPI microservice) que oferece chatbot conversacional com processamento avançado de datas em linguagem natural. Gerencia agendamentos, autenticação de usuários e dashboard administrativo.
Instalação
npx convez-ai OthmanMohammad/dental-chatbot1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de agendamentos em clínicas odontológicas
- Processamento de linguagem natural para datas e horários flexíveis
- Dashboard de gerenciamento de consultas com cancelamento e reagendamento
Veredito

Solução bem estruturada para automação de agendamentos em consultórios. Arquitetura polida com separação clara de responsabilidades (Node/Express para negócio, FastAPI para IA) e implementação robusta de date parsing em linguagem natural, apropriada para clínicas que buscam modernizar processos.
README
A tradução para o português deste README ainda está na fila.
Dental Chatbot - AI Appointment Booking System
basically built a chatbot that helps people book dental appointments using Claude AI and it turned out pretty solid i think
What This Thing Does
so the main idea is you have a dental clinic and patients can chat with an AI assistant to book appointments, the bot asks what kind of appointment they need (cleaning, checkup, etc) and when they want it, then it actually books it in the database. plus theres a dashboard where you can see all your appointments and cancel or reschedule them
the cool part is it handles natural language really well like if someone says "tomorrow at 2pm" or "next week tuesday" it figures it out, i spent way too much time on the date parsing logic but it was worth it
Demo
Tech Stack
Frontend:
- Next.js 14 (React framework)
- Just vanilla CSS, no fancy UI library because didnt want to overcomplicate
- Axios for API calls
Backend API:
- Node.js with Express 5
- PostgreSQL for database
- JWT for auth
- bcrypt for password hashing
- pretty standard REST API setup
Python Microservice:
- FastAPI (way faster than Flask for this)
- LangChain for the AI stuff
- Anthropic Claude (using claude-3-5-haiku because its fast and cheap)
- psycopg2 for postgres connection
Architecture Overview
so basically its a 3-tier thing:
- Frontend - Next.js app that users interact with, handles login/register and chat interface
- Backend API - Node/Express server that manages auth, appointments, and generates chatbot tokens
- Python Service - FastAPI app that runs the actual chatbot using LangChain and Claude
the reason i split it like this is because the Node backend handles all the business logic and database stuff for appointments while the Python service is purely focused on AI chat, makes it easier to scale later and also keeps concerns separated
the flow is like: user logs in → gets JWT token → frontend calls backend to get chatbot token → uses chatbot token to talk to python service → python service books appointments by calling backend API
Setup Instructions
ok so heres how to get everything running, its not too complicated but theres a few steps
Prerequisites
you need these installed:
- Node.js (i used v18 but anything recent should work)
- Python 3.9+
- PostgreSQL (i tested on 13 but 12+ should be fine)
- an Anthropic API key (get from console.anthropic.com)
Database Setup
first thing is setup the database
# login to postgres
psql -U postgres
# create database
CREATE DATABASE dental_chatbot;
# connect to it
\c dental_chatbot
# now run the schema file
\i /path/to/database/schema.sql
or if you prefer you can just copy paste the contents of database/schema.sql into psql terminal, either way works. this creates all the tables (users, appointments, chat_sessions, chat_messages) and adds some sample data
Backend Setup
navigate to backend folder and install dependencies:
cd backend
npm install
create .env file (theres a .env.example you can copy):
cp .env.example .env
then edit the .env file with your actual values:
PORT=3001
JWT_SECRET=your-secret-key-here-use-something-random
NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_NAME=dental_chatbot
DB_USER=postgres
DB_PASSWORD=your-postgres-password
important: change the JWT_SECRET to something random, dont use the default in production obviously
start the server:
npm run dev
should see "Server running on port 3001" if everything worked
Python Service Setup
go to python service folder:
cd python-service
create virtual environment (recommended so you dont mess up your system python):
python -m venv venv
# activate it
# on windows:
venv\Scripts\activate
# on mac/linux:
source venv/bin/activate
install requirements:
pip install -r requirements.txt
create .env file:
cp .env.example .env
edit it with your settings:
PORT=8000
ANTHROPIC_API_KEY=your-anthropic-key-here
BACKEND_URL=http://localhost:3001
JWT_SECRET=same-as-backend-jwt-secret
DB_HOST=localhost
DB_PORT=5432
DB_NAME=dental_chatbot
DB_USER=postgres
DB_PASSWORD=your-postgres-password
critical: the JWT_SECRET here needs to match the one in backend otherwise token verification fails and nothing works
run the service:
python main.py
or if you prefer uvicorn directly:
uvicorn main:app --reload --port 8000
should see startup messages and "database ready" if db connection worked
Frontend Setup
open new terminal, go to frontend folder:
cd frontend
npm install
create .env.local file:
cp pages/.env.local.example .env.local
edit it:
NEXT_PUBLIC_BACKEND_URL=http://localhost:3001
NEXT_PUBLIC_PYTHON_URL=http://localhost:8000
start the dev server:
npm run dev
frontend should be running on http://localhost:3000
Testing the App
ok so now everything should be running, you can test the full flow:
- open browser to http://localhost:3000
- click register and create account (use any email format, doesnt need to be real)
- after registering, login with those credentials
- you'll be redirected to chat page
- try saying something like "i need a cleaning appointment"
- bot will ask when you want it
- say "tomorrow at 2pm" or "next week 3pm" or whatever
- bot should book it and confirm
- click dashboard button to see your appointments
- you can cancel or reschedule from dashboard (reschedule just alerts for now, didnt implement the modal yet)
the chat history persists in database so if you refresh page it loads your previous messages
Project Structure
quick overview of how files are organized:
backend/
├── server.js # main express app
├── db.js # database connection pool
├── middleware/ # auth, logging, rate limiting
├── services/ # business logic layer
├── repositories/ # database operations
└── routes/ # API endpoints
python-service/
├── main.py # fastapi app and endpoints
├── services/ # chat orchestration, date parsing
└── repositories/ # database operations for chat
frontend/
└── pages/
├── index.js # redirects to login/chat
├── login.js # login/register page
├── chat.js # main chat interface
└── dashboard.js # appointments dashboard
i tried to keep it organized with separation of concerns, like repositories handle all database stuff, services have business logic, routes are just thin controllers
API Endpoints
just documenting the main ones real quick:
Backend (port 3001):
POST /api/auth/register
POST /api/auth/login
POST /api/auth/chatbot/token # generates chatbot session token
GET /api/appointments # get user's appointments
POST /api/appointments # create new appointment
PUT /api/appointments/:id # reschedule appointment
DELETE /api/appointments/:id # cancel appointment
Python Service (port 8000):
GET /health # health check
POST /chat # main chat endpoint
GET /chat/history/{session_id} # load chat history
all endpoints except register/login need Authorization header with Bearer token
How the AI Chatbot Works
so the chatbot uses LangChain with Claude 3.5 Haiku model, i chose haiku because its fast enough and way cheaper than opus while still being pretty capable for this use case
the key thing is i gave Claude a "tool" (function calling in LangChain terminology) called create_appointment that it can call when it has all the info needed. the system prompt tells Claude to ask for appointment type and date/time, once it has both it calls the tool which triggers my python code to actually book the appointment via the backend API
the date parsing was honestly the trickiest part because users say stuff like "day after tomorrow" or "14 days from now at 3pm" and i needed to convert that to actual datetime, so i built a parser that handles common patterns and also falls back to dateutil for weird cases. then theres validation to make sure the date is in the future, during business hours, on a weekday, etc
conversation history is stored in postgres so when you come back later it remembers the context, each session has a unique ID based on user + date so conversations persist across page refreshes
Design Decisions & Trade-offs
Why separate python service instead of doing everything in Node? honestly i could have done it all in Node but the LangChain ecosystem is way more mature in Python and Anthropic's SDK works better there too, plus it makes it easier to add other AI features later without touching the main backend
Why not use websockets for chat? considered it but HTTP polling is simpler and for a chatbot where responses take a few seconds anyway it doesnt matter much, websockets would be overkill here
Why JWT instead of sessions? JWT is stateless which makes it easier to scale horizontally later, and i didnt want to deal with session storage (redis etc) for a prototype
Why PostgreSQL? need relational db for appointments/users with foreign keys, postgres is solid and free, plus the JSONB type is nice for storing chat metadata if needed
Repository pattern - was it worth it? probably overkill for this small project but it makes testing easier and keeps the code cleaner, like if i need to swap out the database layer later its all in one place
Known Issues / TODOs
few things i didnt get to finish:
- reschedule modal on dashboard is just an alert, needs proper implementation
- no email verification or password reset
- rate limiting is in-memory which doesnt work across multiple instances
- should add redis for session storage and caching
- chat UI could use some polish (typing indicators work tho)
- no error boundary on frontend so if something crashes it just breaks
- date parser might struggle with ambiguous dates like "next friday" if its currently friday
- appointment slots dont check actual dentist availability, just time conflicts
also the code has some inconsistencies because i refactored it partway through, like some files use different naming conventions but it all works
Security Considerations
for production you'd want to:
- use HTTPS everywhere obviously
- add CORS whitelist instead of allowing all origins
- implement refresh tokens not just access tokens
- add rate limiting per user not just per IP
- sanitize all user inputs better (i have basic validation but could be stricter)
- use environment-specific secrets not hardcoded defaults
- add API request signing between services
- implement proper logging and monitoring
- database credentials should be in secrets manager not .env files
but for a prototype/assessment this security level is reasonable i think
Deployment Notes
didnt deploy this anywhere but if you were going to:
Backend & Python Service:
- could use AWS ECS/Fargate or just EC2 instances
- both services behind ALB
- RDS for postgres
- ElastiCache Redis for sessions/cache
- CloudWatch for logs
Frontend:
- Vercel is easiest for Next.js (literally just connect github and deploy)
- or AWS Amplify works too
- or build static export and put on S3+CloudFront if you dont need SSR
Environment Variables:
- use AWS Systems Manager Parameter Store or Secrets Manager
- never commit .env files to git (they're in .gitignore but still)
Performance Thoughts
havent done extensive testing but from what i saw:
- chatbot responses are pretty fast, usually under 2 seconds
- date parsing is instant
- database queries are quick with the indexes i added
- frontend loads reasonably fast, could optimize bundle size though
if this scaled to high traffic would need to:
- add caching layer (redis) for common queries
- database connection pooling (already have but might need tuning)
- CDN for frontend assets
- maybe add queue system for chat requests if volume gets crazy
- horizontal scaling should work since most stuff is stateless
Testing
honestly didnt write automated tests because of time constraints but did manual testing:
- tried booking appointments with various date formats
- tested edge cases like past dates, weekends, after hours
- checked that appointment conflicts get detected properly
- verified chat history persists correctly
- tested auth flows (register, login, token refresh)
if i had more time would add:
- Jest tests for backend services
- pytest for python service
- React Testing Library for frontend components
- integration tests for full user flows
- load testing with something like k6
Final Thoughts
overall this was fun to build, the AI integration worked out way better than i expected and the date parsing actually handles most inputs pretty well. the architecture is clean enough that adding features later shouldnt be too painful
the main challenge was getting all 3 services to talk to each other properly with the auth tokens and making sure the database connection pooling worked right, but once that was sorted it came together pretty quick
if i was building this for real production would definitely add more error handling and monitoring, and probably use TypeScript instead of plain JavaScript, but for a prototype its solid
let me know if anything's unclear or doesnt work!