- Tech Stack
- Repo Structure
- Development Setup
- Application Execution
- API Testing with Postman
- Database Interactions
- Version Control Guide
- Formatting and Linting
- Testing
- FAQ & Debugging
Frontend: React, TypeScript
Backend: Python, FastAPI, SQLModel
Database: PostgreSQL
Authentication: Firebase Auth
Containerization: Docker & Docker Compose
food4kids/
├── backend/
│ └── python/
│ ├── app/
│ │ ├── dependencies/ # Dependency injection (auth, etc.)
│ │ ├── migrations/ # Alembic database migrations
│ │ ├── models/ # SQLModel database models
│ │ ├── routers/ # FastAPI route handlers
│ │ ├── schemas/ # Pydantic schemas for API
│ │ ├── services/ # Business logic layer
│ │ │ ├── implementations/ # Concrete service implementations
│ │ │ └── jobs/ # Scheduled Cron Jobs
│ │ │ └── protocols/ # Algorithms and how the server handles data
│ │ ├── templates/ # Email/HTML templates
│ │ └── utilities/ # Shared utility functions
│ ├── tests/ # Unit and functional tests
│ ├── alembic.ini # Alembic configuration
│ ├── requirements.txt # Python dependencies
│ └── server.py # Application entry point
├── frontend/ # Frontend (TBD)
├── db-init/ # Database initialization scripts
├── docker-compose.yml # Multi-container Docker setup
└── README.md
- Install Docker Desktop and ensure it's running
- Clone this repository:
git clone [email protected]:uwblueprint/food4kids.git
cd food4kidsYou will need to create environment files: .env and frontend/.env. Talk to the PL to obtain these.
Build and start all services using Docker Compose:
docker-compose up --buildThis will start:
- Frontend: React development server on port 3000
- Backend: FastAPI server on port 8080
- Database: PostgreSQL on port 5432
# Start all services
docker-compose up --build
# Start in detached mode (background)
docker-compose up -d --buildAccess Points:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8080
- API Documentation: http://localhost:8080/docs (development only)
- ReDoc Documentation: http://localhost:8080/redoc (development only)
Postman is a powerful tool for testing API endpoints during development. For detailed setup instructions and best practices, see our Postman Setup Guide.
Quick Start:
- Ensure the backend container is running (
docker-compose up) - Import the Postman collection (if available) or manually configure requests
- Set the base URL to
http://localhost:8080 - Configure authentication headers as needed (see the Notion guide for details)
Alternative: You can also test endpoints using the interactive Swagger UI at http://localhost:8080/docs
The project uses Alembic for database migrations. All commands run from the project root:
# Check current migration status
docker-compose exec backend alembic current
# Generate new migration (auto-detect model changes)
docker-compose exec backend alembic revision --autogenerate -m "description_of_changes"
# Apply pending migrations
docker-compose exec backend alembic upgrade head
# Check if database schema matches models
docker-compose exec backend alembic check
# View migration history
docker-compose exec backend alembic history# Connect to development database
docker-compose exec db psql -U postgres -d f4k
# Connect to test database
docker-compose exec db psql -U postgres -d f4k_test
# Once inside the DB, try these common PostgreSQL commands:
\dt # List all tables
\d table_name # Describe table structure
\q # Quit
SELECT * FROM users; # Run SQL queries# Populate database with randomized test data
docker-compose exec backend python app/seed_database.py- Branch off
mainfor all feature work and bug fixes - Use descriptive branch names in kebab-case:
username/feature-description - Example:
colin/user-authentication-fix
Use rebase instead of merge to integrate main changes:
# Update feature branch with main changes
git pull origin main --rebase
# If conflicts occur, resolve them and continue
git add .
git rebase --continue
# Force push to remote feature branch
git push --force-with-lease# Build images
docker-compose build
# Start containers (builds if needed)
docker-compose up
# Start with fresh build
docker-compose up --build
# Stop containers
docker-compose down
# Stop containers and remove volumes
docker-compose down --volumes
# View running containers
docker ps
# Clean up unused Docker resources
docker system prune -a --volumesThe project uses Ruff for Python linting and formatting, and mypy for static type checking:
# Check for linting issues
docker-compose exec backend ruff check .
# Auto-fix linting issues
docker-compose exec backend ruff check --fix .
# Format code
docker-compose exec backend ruff format .
# Check formatting without making changes
docker-compose exec backend ruff format --check .# Run type checking
docker-compose exec backend mypy .# Run all quality checks (linting, formatting, type checking)
docker-compose exec backend ruff check . && docker-compose exec backend ruff format --check . && docker-compose exec backend mypy .Configuration Files:
- Ruff:
backend/python/pyproject.toml(under[tool.ruff]) - mypy:
backend/python/mypy.ini
# Check linting issues
docker-compose exec frontend npm run lint
# Auto-fix linting issues
docker-compose exec frontend npm run fix
# Combined format and lint (when available)
docker-compose exec frontend npm run format# Run all backend tests
docker-compose exec backend python -m pytest
# Run specific test file
docker-compose exec backend python -m pytest tests/unit/test_models.py
# Run with coverage
docker-compose exec backend python -m pytest --cov=app# Run frontend tests
docker-compose exec frontend npm test
# Run tests in CI mode
docker-compose exec frontend npm test -- --ci --coverage --watchAll=falseNote: CI/CD pipeline for automated testing will be added in future updates.
How do I test API endpoints?
- Ensure the backend container is running
- Visit http://localhost:8080/docs for interactive API documentation
- Use the "Authorize" button to add your Firebase auth token
- Test endpoints in Postman or directly in the Swagger UI
Database connection errors
- Ensure Docker Desktop is running
- Check that the database container is healthy:
docker-compose ps - Verify environment variables in
.envfile - Try rebuilding containers:
docker-compose down --volumes && docker-compose up --build
"ENOSPC: no space left on device" when building containers
Clean up Docker resources:
docker system prune -a --volumes
docker-compose up --buildMigration errors
- Check current migration status:
docker-compose exec backend alembic current - Ensure database is running and accessible
- Verify model changes are properly defined in
app/models/ - For migration conflicts, you may need to manually resolve in the database
Firebase authentication issues
- Verify Firebase configuration in environment files
- Check that Firebase project settings match your configuration
- Ensure Firebase Admin SDK credentials are properly formatted
- Fork the repository
- Create a feature branch from
main - Make your changes following the coding standards
- Run tests and linting
- Submit a pull request with a clear description
[Add license information here]