Development Setup¶

Set up your development environment for contributing to Duckling.

Prerequisites¶

• Python 3.10+
• Node.js 18+
• Git

Backend Setup¶

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Frontend Setup¶

cd frontend
npm install

Running Development Servers¶

Backend¶

cd backend
source venv/bin/activate
python app.py

Backend runs at: http://localhost:5001

Frontend¶

cd frontend
npm run dev

Frontend runs at: http://localhost:3000

Project Structure¶

duckling/
├── backend/
│   ├── app.py              # Flask application entry
│   ├── config.py           # Configuration
│   ├── models/             # Database models
│   ├── routes/             # API endpoints
│   ├── services/           # Business logic
│   └── tests/              # Backend tests
├── frontend/
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── hooks/          # Custom React hooks
│   │   ├── services/       # API client
│   │   └── types/          # TypeScript types
│   └── tests/              # Frontend tests
└── docs/                   # Documentation

IDE Setup¶

VS Code¶

Recommended extensions:

• Python
• Pylance
• ESLint
• Prettier
• Tailwind CSS IntelliSense

Settings¶

.vscode/settings.json:

{
  "python.defaultInterpreterPath": "./backend/venv/bin/python",
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Environment Variables¶

Create .env files for local development:

Backend (.env)¶

FLASK_ENV=development
SECRET_KEY=dev-secret-key
DEBUG=True

Frontend (.env.local)¶

VITE_API_URL=http://localhost:5001/api

Hot Reloading¶

Both servers support hot reloading:

• Backend: Flask debug mode auto-reloads on file changes
• Frontend: Vite HMR updates components without page refresh

Debugging¶

Backend (VS Code)¶

.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Flask",
      "type": "python",
      "request": "launch",
      "module": "flask",
      "env": {
        "FLASK_APP": "app.py",
        "FLASK_DEBUG": "1"
      },
      "args": ["run", "--port", "5001"],
      "jinja": true,
      "cwd": "${workspaceFolder}/backend"
    }
  ]
}

Frontend¶

Use browser DevTools with React Developer Tools extension.

Common Tasks¶

Update Dependencies¶

# Backend
cd backend
pip install --upgrade -r requirements.txt

# Frontend
cd frontend
npm update

Generate Types¶

cd frontend
npm run generate-types  # If available

Build for Production¶

# Frontend
cd frontend
npm run build

# Backend (no build needed)