Contributing Guide¶

Thank you for your interest in contributing to the Livestock Tracking Platform! This guide will help you get started.

Getting Started¶

Prerequisites¶

Python 3.11+ - Backend development
Node.js 20+ - Frontend development
Docker & Docker Compose - Running services
Git - Version control

Setup Development Environment¶

Fork the repository

Clone your fork

git clone https://github.com/YOUR_USERNAME/livestock-tracking
cd livestock-tracking

Start the services
```
make up
```
Verify services are running
```
docker-compose ps
```

Project Structure¶

livestock-tracking/
├── app/                    # Backend (Python/FastAPI)
│   ├── api/               # API endpoints
│   ├── core/              # Config & database
│   ├── models/            # SQLAlchemy models
│   ├── schemas/           # Pydantic schemas
│   └── worker/            # Background workers
├── frontend/              # Frontend (Next.js)
│   ├── src/
│   │   ├── app/          # Pages
│   │   ├── components/   # React components
│   │   └── lib/          # Utilities
│   └── package.json
├── docs/                  # Documentation
├── scripts/               # Utility scripts
├── docker/                # Docker configs
├── Makefile              # Build commands
└── docker-compose.yml    # Container orchestration

Making Changes¶

Backend Changes¶

Create a virtual environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

Install dependencies
```
pip install -r requirements.txt
```
Make your changes
Follow existing code style
Add type hints
Write docstrings for new functions

Test locally

# Run the API
python -m uvicorn app.main:app --reload --port 8000

Frontend Changes¶

Install dependencies
```
cd frontend
npm install
```
Make your changes
Follow React best practices
Use TypeScript
Follow existing component patterns
Test locally
```
npm run dev
```

Database Changes¶

If you modify models:

Generate migration

# Not implemented yet - manual SQL required

Update database directly

docker exec -it livestock-postgres psql -U livestock -d livestock_db

Code Style¶

Python¶

Follow PEP 8
Use type hints
Use Black for formatting
Use isort for imports

pip install black isort
black .
isort .

TypeScript/JavaScript¶

Use ESLint and Prettier
Follow Airbnb style guide

cd frontend
npm run lint

Testing¶

Backend Tests¶

# Not implemented yet
pytest

Frontend Tests¶

cd frontend
npm test

Submitting Changes¶

Create a branch

git checkout -b feature/your-feature-name

Make commits

git add .
git commit -m "Add your feature"

Push to your fork

git push origin feature/your-feature-name

Create a Pull Request

Common Tasks¶

Add a New API Endpoint¶

Create or modify endpoint in app/api/telemetry.py
Add Pydantic schema in app/schemas/__init__.py
Test endpoint at http://localhost:8000/docs

Add a New Component¶

Create component in frontend/src/components/
Import in frontend/src/app/page.tsx
Use existing UI components from frontend/src/components/ui/

Add a New Database Model¶

Add model in app/models/__init__.py
Create table manually or via migration
Add schema in app/schemas/__init__.py

Debugging¶

Backend Debugging¶

# Add logging
import logging
logger = logging.getLogger(__name__)
logger.info("Your message")

Frontend Debugging¶

// Add console logs
console.log('Your message', data);

// Use React DevTools

Docker Debugging¶

# View logs
docker-compose logs -f api

# Enter container
docker exec -it livestock-api sh

# Check environment
docker-compose exec api env

Resources¶

Questions?¶

Open an issue for bugs or feature requests
Join the discussion in GitHub Discussions
Check existing issues before creating new ones