🐾 5Pets Development Guide

Your Complete Pet Care Platform - Local Development Setup

Features • Quick Start • Architecture • Documentation

---

🌟 Key Features

🎨 Modern Frontend Next.js-powered responsive UI with seamless UX

⚡ Robust Backend Flask API with efficient data processing

🤖 AI Integration Intelligent pet consultation chatbot

---

🚀 Quick Start

# Clone the repository
git clone <repository-url>
cd 5pets

# Backend Setup
cd src/server
python -m venv .env.bin
source .env.bin/bin/activate  # Windows: .env.bin\Scripts\activate
pip install -r requirements.txt
python app.py

# Frontend Setup (in new terminal)
cd src/client
npm install
echo "NEXT_PUBLIC_API_URL=http://localhost:10000/api" > .env
npm run dev

🎉 Done! Visit http://localhost:3000

---

📐 Architecture

graph LR
    A[🖥️ Client<br/>Next.js:3000] -->|REST API| B[⚙️ Backend<br/>Flask:10000]
    B --> C[🤖 AI Module<br/>Pet Consultant]
    B --> D[🗄️ Data Layer<br/>Storage]
    
    style A fill:#0070f3,stroke:#fff,color:#fff
    style B fill:#10b981,stroke:#fff,color:#fff
    style C fill:#f59e0b,stroke:#fff,color:#fff
    style D fill:#6366f1,stroke:#fff,color:#fff

Loading

📁 Project Structure

5pets/
┣━━ 📂 data/                    Raw datasets and crawled data
┣━━ 🎨 design/                  UI/UX mockups and assets
┣━━ 📋 pa/                      Project proposals and architecture docs
┣━━ 📚 docs/                    API specifications and manuals
┃
┗━━ 💻 src/                     Core application source
    ┣━━ ⚛️ client/              Next.js frontend application
    ┣━━ 🐍 server/              Flask backend API service
    ┗━━ 🤖 ai_pet_consultant/   AI chatbot logic module

---

🛠️ Prerequisites

Ensure your development environment has the following installed:

Technology	Version	Download
Node.js	≥ 18.x	nodejs.org
Python	≥ 3.10	python.org
Git	Latest	git-scm.com

Quick Check:

node --version && python --version && git --version

---

📘 Detailed Setup

🖥️ Frontend Configuration

📍 Location: src/client

Step 1: Environment Variables

Create .env file:

# Backend API Endpoint
NEXT_PUBLIC_API_URL=http://localhost:10000/api

# Optional: Other configurations
# NEXT_PUBLIC_ANALYTICS_ID=your_analytics_id

Step 2: Install Dependencies

cd src/client
npm install

Step 3: Development Server

npm run dev

✅ Frontend running at: http://localhost:3000

Available Scripts

Command	Description
npm run dev	Start development server with hot reload
npm run build	Create production build
npm start	Run production server
npm run lint	Check code quality

---

⚙️ Backend Configuration

📍 Location: src/server

Step 1: Virtual Environment

cd src/server

# Create virtual environment
python -m venv .env.bin

# Activate it
source .env.bin/bin/activate  # macOS/Linux
# OR
.env.bin\Scripts\activate     # Windows

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: Start Flask Server

python app.py

✅ Backend API running at: http://localhost:10000

Environment Variables (Optional)

Create .env file in src/server:

FLASK_ENV=development
FLASK_DEBUG=True
SECRET_KEY=your_secret_key_here
DATABASE_URL=your_database_connection

---

🤖 AI Module Setup

📍 Location: src/ai_pet_consultant

This module powers the intelligent pet consultation features.

Installation

cd src/ai_pet_consultant

# Create isolated environment (recommended)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install AI dependencies
pip install -r requirements.txt

Configuration

Configure AI model settings in config.py or via environment variables.

---

🎯 Running Complete Stack

Option 1: Multi-Terminal Approach

Terminal 1 - Backend:

cd src/server
source .env.bin/bin/activate
python app.py

Terminal 2 - Frontend:

cd src/client
npm run dev

Option 2: Using Process Manager (Recommended)

Install concurrently:

npm install -g concurrently

Run from project root:

concurrently "cd src/server && python app.py" "cd src/client && npm run dev"

---

🔧 Troubleshooting

🚨 Common Issues

Port Already in Use

Frontend (Port 3000):

# Find process
lsof -ti:3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Kill process or change port in package.json

Backend (Port 10000):

# Change port in app.py
app.run(port=10001)  # Use different port

# Update frontend .env
NEXT_PUBLIC_API_URL=http://localhost:10001/api

CORS Errors

Ensure flask-cors is configured in app.py:

from flask_cors import CORS

app = Flask(__name__)
CORS(app, origins=["http://localhost:3000"])

Module Not Found Errors

# Verify virtual environment is activated
which python  # Should show venv path

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Environment Variables Not Loading

• Restart the development server after changing .env
• Check file name is exactly .env (not .env.txt)
• Ensure no spaces around = in variable assignments

---

📚 Additional Resources

• 📖 API Documentation
• 🎨 Design System
• 🏗️ Architecture Details
• 🐛 Bug Reports

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

💝 Built with Love by the 5Pets Team

Questions? Open an issue or contact us at team@5pets.dev

⬆️ Back to Top