Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
  • Node.js 20+ - For the frontend application
  • Python 3.9+ - For the backend API
  • PostgreSQL 15 - Database server
  • Git - For cloning the repository
If you prefer using Docker, see the Docker Setup guide for containerized development.

​
Cloning the Repository

Clone the SmartEat AI repository to your local machine: 
git clone https://github.com/SmartEatAI/smart-eat-ai.git
cd smart-eat-ai

​
Environment Configuration

Copy the example environment file and configure your local settings: 
cp .env.example .env
Edit the .env file with your local credentials. See the Environment Variables reference for detailed descriptions of each variable.
Make sure to update the SECRET_KEY with a secure random string before running in production.

​
Backend Installation

1

Navigate to backend directory

cd backend
2

Install Python dependencies

pip install -r ../docker/backend/requirements.txt
This installs all required packages including:
  • FastAPI - Web framework
  • SQLAlchemy - Database ORM
  • Alembic - Database migrations
  • scikit-learn, joblib - ML models
  • LangChain, LangGraph - AI agents
3

Run database migrations

Apply all database migrations to set up the schema:
alembic upgrade head
4

(Optional) Seed the database

Populate the database with sample data:
python app/seeders/run_seed.py
This inserts users, categories, profiles, recipes, and meal plans.
5

Start the backend server

uvicorn app.main:app --reload
The API will be available at:

​
Backend Health Check

Verify the backend is running correctly: 
curl http://localhost:8000/health

​
Frontend Installation

1

Navigate to frontend directory

cd frontend
2

Install Node dependencies

npm install
This installs:
  • Next.js - React framework
  • TypeScript - Type safety
  • Tailwind CSS - Styling
  • React Context API - State management
3

Start the development server

npm run dev
The frontend will be available at http://localhost:3000

​
Verification

Once both services are running, you should be able to:
  1. Access the frontend at http://localhost:3000
  2. Create a new user account
  3. Log in and complete your profile
  4. View the dashboard and interact with the chat
The frontend needs the backend API to be running to function properly. Make sure both services are started.

​
Database Migrations

Whenever you modify database models, create and apply migrations: 
alembic revision --autogenerate -m "describe your change"

​
Development Tools

​
API Documentation

​
Code Quality

The frontend includes ESLint and Prettier for code quality: 
npm run lint

​
Troubleshooting

​
Backend Issues

Database connection errors
  • Verify PostgreSQL is running
  • Check DATABASE_URL in .env matches your PostgreSQL credentials
  • Ensure the database exists: createdb smarteatai
Migration errors
  • Delete the alembic/versions folder and start fresh
  • Check for model conflicts in backend/app/models/

​
Frontend Issues

Port already in use 
# Change the port in package.json or kill the process
lsof -ti:3000 | xargs kill -9
Module not found errors 
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us