Open-source platform for animal shelter management
Quick Start • Documentation • Development • Contributing
Hackapet is a comprehensive, open-source web platform designed specifically for animal shelter management. Built with modern technologies and professional development practices, it provides a secure, scalable, and user-friendly solution for shelter operations.
Born from direct collaboration with rescue organizations like SOS Peludetes, the platform addresses real operational challenges faced by shelters that typically rely on paper records, spreadsheets, and messaging apps.
PetSync is one of the flagship products: a full-stack animal shelter management system designed to streamline operations, improve transparency, and ultimately help save more animals.
- Frontend: Angular 20.1 + TypeScript
- Backend: Django 5.1 + REST Framework + PostgreSQL
- Infrastructure: Docker + Docker Compose
- Deployment: Production-ready containerization
- Animal Management - Complete digital profiles with medical history, behavior tracking, and rescue documentation
- Integrated Calendar - Veterinary appointments, adoption visits, and event scheduling with automatic notifications
- Social Media Automation - Automated posting to multiple platforms when animals become available for adoption
- Adoption Portal - Public-facing interface for potential adopters to search and connect with animals
- Financial Transparency - Automated tracking and reporting of expenses per animal to build donor trust
- Medical Records - Store vaccination schedules, treatment plans, photos of medical documents, and health tracking
- Flexible Notes System - Open comment areas alongside structured data fields for comprehensive record-keeping
- One-command setup -
make upto start development environment - Hot reload - Instant feedback during development with Angular and Django dev servers
- Automated testing - Frontend (Karma/Jasmine) + Backend (Django test framework)
- Docker containerization - Consistent development and production environments
- API versioning - Structured API design for stability and backward compatibility
- Environment-based configuration - No hardcoded secrets, secure development practices
- PostgreSQL database - Production-grade database with automated migrations
- JWT authentication ready - Secure token-based authentication with djangorestframework-simplejwt
- ULID-based IDs - Unique, sortable identifiers for all entities
- TypeScript strict mode - Type safety and code quality enforcement
- Docker Desktop - Download here
- Node.js 18+ - Download here (for local frontend development)
- Make - Usually pre-installed on macOS/Linux
# 1. Clone the repository
git clone hhttps://github.com/hackapet-project/petsync_web_V2.git
cd petsync_web_V2
# 2. Start the development environment
make up
# 3. Apply database migrations
make migrateOnce the environment is running:
| Service | URL | Description |
|---|---|---|
| Frontend | http://localhost:4000 | Angular development server |
| Backend | http://localhost:9001 | Django API server |
| Admin Panel | http://localhost:9001/admin | Django administration |
# Apply database migrations
make migrate
# Create a superuser for admin access
make superuser
# View logs
docker compose logs -f# Development
make up # Start full development environment
make down # Stop all containers
make build # Build/rebuild containers
# Database
make migrations # Create and apply migrations
make migrate # Apply migrations only
# Testing
make test_back # Run backend tests
# Utilities
make create_app i=app_name # Create new Django appcd front
# Install dependencies
npm install
# Start dev server
npm start
# or: ng serve
# Run tests
npm test
# or: ng test
# Build for production
npm run build
# or: ng buildpetsync_web_V2/
├── back/ # Django backend
│ ├── api/ # Core API
│ │ ├── models/ # User, Animal, Shelter models
│ │ └── v1/ # API versioning
│ ├── core/ # Django settings and configuration
│ └── manage.py # Django management
├── front/ # Angular frontend
│ ├── src/ # Angular components and logic
│ ├── src/test/ # Frontend test utilities
│ └── angular.json # Angular CLI configuration
├── docker-compose.yml # Multi-service orchestration
├── Makefile # Development automation
└── README.md # This file
- API versioning - Located in
/back/api/v1/ - Core models - User, Animal, Shelter in
/back/api/models/
Backend (Django)
- Django 5.1.x with Django REST Framework
- Custom User model (
AUTH_USER_MODEL = 'api.User') - Core models: User, Animal, Shelter
- API versioning structure in
/back/api/v1/ - SQLite database for development, PostgreSQL for production
- ULID for ID generation (python-ulid)
- JWT authentication ready (djangorestframework-simplejwt)
Frontend (Angular)
- Angular 20.1.x with standalone components
- TypeScript with strict configuration
- Karma + Jasmine for testing
- Angular CLI for development and build tools
- Mobile-first responsive design
Infrastructure
- Docker for containerization
- Docker Compose for orchestration
- Hot reload for both frontend and backend
- Production-ready configuration
# Backend tests
make test_back
# or: docker compose run --rm back pytest
# Frontend tests
cd front && npm test
# or: cd front && ng testThe project follows:
- Backend: Django best practices, Django REST Framework conventions
- Frontend: Angular style guide, TypeScript strict mode
- Testing: Comprehensive test coverage for critical features
The application is production-ready with optimized Docker configurations:
# Build production images
make build
# Production environment variables needed:
# - DJANGO_SECRET_KEY (generate new)
# - DATABASE_URL (PostgreSQL connection)
# - DJANGO_ALLOWED_HOSTS (your domain)
# - DJANGO_DEBUG=FalseConfigure your production environment with:
# Example production configuration
DJANGO_SECRET_KEY=your-super-secure-secret-key
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
DATABASE_URL=postgresql://user:password@host:port/database- Basic CRUD for animal management (starting with dogs)
- Event calendar system
- Social media automation prototype
- Complete adoption workflow
- Financial transparency dashboard
- Enhanced social media templates
- Multi-species support (cats and other animals)
- Geolocation for rescues
- Performance optimization for multiple shelters
- Donation system integration
We welcome contributions from developers, designers, and animal welfare advocates worldwide!
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Run
make upto get started - Make your changes following our code standards
- Test with
make test_backandnpm test - Submit a pull request
- Follow existing code conventions
- Write tests for new features
- Update documentation as needed
- Ensure all tests pass before submitting PRs
- Use meaningful commit messages
Mission: Develop accessible and effective technological tools that enable animal shelters to optimize their operations, increase rescue capacity, and improve the living conditions of animals in their care.
Core Values:
- Direct Social Impact: Every feature must measurably improve animal welfare or shelter efficiency
- Operational Transparency: Complete visibility of processes, expenses, and animal status
- Digital Accessibility: Intuitive interfaces for users of all technical skill levels
- Community Collaboration: Fostering participation from developers, designers, and volunteers
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
This ensures that all modifications and usage in networks (e.g., as a web app) remain open-source. This project is open source to ensure animal shelters worldwide can access these tools regardless of budget constraints.
Special thanks to SOS Peludetes and their team (Felipe Gadea, Empar, Pili, Toñi, and Ignacio L. D.) for their invaluable feedback and real-world insights that shaped this platform's development.
- Bug Reports: GitHub Issues
- Feature Requests: GitHub Discussions
- General Questions: Open an issue or reach out through project channels
Docker not starting?
# Check if Docker is running
docker --version
docker compose version
# Start Docker Desktop and try again
make upEnvironment issues?
# Stop containers
make down
# Rebuild and restart
make build
make upPort conflicts?
If you see port conflict errors, check the ports in docker-compose.yml:
- Frontend: 4000 (maps to internal port 3000)
- Backend: 9001 (maps to internal port 8000)
Built by the Hackapet Team for animal welfare organizations worldwide