convez.ai
PluginAutomaçãoIntermediário
OthmanMohammad

Dental Chatbot - Sistema de Agendamento com IA

OthmanMohammad/dental-chatbot

Chatbot conversacional para agendamento automático de consultas dentárias

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema 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-chatbot

1 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

Estrelas
0
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 1 ano
Versão
—
Issues abertas
0
Contribuidores
1

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

Demo Video

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:

  1. Frontend - Next.js app that users interact with, handles login/register and chat interface
  2. Backend API - Node/Express server that manages auth, appointments, and generates chatbot tokens
  3. 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:

  1. open browser to http://localhost:3000
  2. click register and create account (use any email format, doesnt need to be real)
  3. after registering, login with those credentials
  4. you'll be redirected to chat page
  5. try saying something like "i need a cleaning appointment"
  6. bot will ask when you want it
  7. say "tomorrow at 2pm" or "next week 3pm" or whatever
  8. bot should book it and confirm
  9. click dashboard button to see your appointments
  10. 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!


Ver o original no GitHub

Bom para

Relacionados