bakery-ia/docs/01-getting-started

Getting Started with Bakery IA

Welcome to Bakery IA! This guide will help you get up and running quickly with the platform.

Overview

Bakery IA is an advanced AI-powered platform for bakery management and optimization. The platform implements a microservices architecture with 15+ interconnected services providing comprehensive bakery management solutions including:

• AI-Powered Forecasting: ML-based demand prediction
• Inventory Management: Real-time stock tracking and optimization
• Production Planning: Optimized production schedules
• Sales Analytics: Advanced sales insights and reporting
• Multi-Tenancy: Complete tenant isolation and management
• Sustainability Tracking: Environmental impact monitoring

Prerequisites

Before you begin, ensure you have the following installed:

Required

• Docker Desktop (with Kubernetes enabled) - v4.0 or higher
• Docker Compose - v2.0 or higher
• Node.js - v18 or higher (for frontend development)
• Python - v3.11 or higher (for backend services)
• kubectl - Latest version (for Kubernetes deployment)

Optional

• Tilt - For live development environment
• Skaffold - Alternative development tool
• pgAdmin - For database management
• Postman - For API testing

Quick Start (Docker Compose)

The fastest way to get started is using Docker Compose:

1. Clone the Repository

git clone <repository-url>
cd bakery-ia

2. Set Up Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit the .env file with your configuration
nano .env  # or use your preferred editor

Key variables to configure:

• JWT_SECRET - Secret key for JWT tokens
• Database passwords (use strong passwords for production)
• Redis password
• SMTP settings (for email notifications)

3. Start the Services

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

4. Verify the Deployment

# Check service health
docker-compose ps

# View logs
docker-compose logs -f gateway

5. Access the Application

• Frontend: http://localhost:3000
• API Gateway: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• pgAdmin: http://localhost:5050 (admin@bakery.com / admin)

Quick Start (Kubernetes - Development)

For a more production-like environment:

1. Enable Kubernetes in Docker Desktop

1. Open Docker Desktop settings
2. Go to Kubernetes tab
3. Check "Enable Kubernetes"
4. Click "Apply & Restart"

2. Deploy to Kubernetes

# Create namespace
kubectl create namespace bakery-ia

# Apply configurations
kubectl apply -k infrastructure/kubernetes/overlays/dev

# Check deployment status
kubectl get pods -n bakery-ia

3. Access Services

# Port forward the gateway
kubectl port-forward -n bakery-ia svc/gateway 8000:8000

# Port forward the frontend
kubectl port-forward -n bakery-ia svc/frontend 3000:3000

Access the application at http://localhost:3000

Development Workflow

Using Tilt (Recommended)

Tilt provides a live development environment with auto-reload:

# Install Tilt
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash

# Start Tilt
tilt up

# Access Tilt UI at http://localhost:10350

Using Skaffold

# Install Skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64
chmod +x skaffold
sudo mv skaffold /usr/local/bin

# Run development mode
skaffold dev

First Steps After Installation

1. Create Your First Tenant

# Register a new user and tenant
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@mybakery.com",
    "password": "SecurePassword123!",
    "full_name": "Admin User",
    "tenant_name": "My Bakery"
  }'

2. Log In

# Get access token
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@mybakery.com",
    "password": "SecurePassword123!"
  }'

Save the returned access_token for subsequent API calls.

3. Explore the API

Visit http://localhost:8000/docs to see interactive API documentation with all available endpoints.

4. Add Sample Data

# Load demo data (optional)
kubectl exec -n bakery-ia deploy/demo-session -- python seed_demo_data.py

Project Structure

bakery-ia/
├── frontend/                 # React frontend application
├── gateway/                  # API gateway service
├── services/                 # Microservices
│   ├── auth/                # Authentication service
│   ├── tenant/              # Multi-tenancy service
│   ├── inventory/           # Inventory management
│   ├── forecasting/         # ML forecasting service
│   ├── production/          # Production planning
│   ├── sales/               # Sales service
│   ├── orders/              # Order management
│   └── ...                  # Other services
├── shared/                  # Shared libraries and utilities
├── infrastructure/          # Kubernetes configs and IaC
│   ├── kubernetes/         # K8s manifests
│   └── tls/                # TLS certificates
├── scripts/                 # Utility scripts
└── docs/                    # Documentation

Common Tasks

View Service Logs

# Docker Compose
docker-compose logs -f <service-name>

# Kubernetes
kubectl logs -f -n bakery-ia deployment/<service-name>

Restart a Service

# Docker Compose
docker-compose restart <service-name>

# Kubernetes
kubectl rollout restart -n bakery-ia deployment/<service-name>

Access Database

# Using pgAdmin at http://localhost:5050
# Or use psql directly
docker-compose exec auth-db psql -U auth_user -d auth_db

Run Database Migrations

# For a specific service
docker-compose exec auth-service alembic upgrade head

Clean Up

# Docker Compose
docker-compose down -v  # -v removes volumes

# Kubernetes
kubectl delete namespace bakery-ia

Troubleshooting

Services Won't Start

1. Check Docker is running: docker ps
2. Check ports are free: lsof -i :8000 (or other ports)
3. View logs: docker-compose logs <service-name>
4. Rebuild: docker-compose up --build --force-recreate

Database Connection Errors

1. Check database is running: docker-compose ps
2. Verify credentials in .env file
3. Check network: docker network ls
4. Reset database: docker-compose down -v && docker-compose up -d

Frontend Can't Connect to Backend

1. Check gateway is running: curl http://localhost:8000/health
2. Verify CORS settings in gateway configuration
3. Check network mode in docker-compose.yml

Kubernetes Pods Not Starting

# Check pod status
kubectl get pods -n bakery-ia

# Describe failing pod
kubectl describe pod -n bakery-ia <pod-name>

# View pod logs
kubectl logs -n bakery-ia <pod-name>

Next Steps

Now that you have the platform running, explore these guides:

1. Architecture Overview - Understand the system design
2. Development Workflow - Learn development best practices
3. API Reference - Explore available APIs
4. Deployment Guide - Deploy to production

Additional Resources

Documentation

• Testing Guide
• Security Overview
• Feature Documentation

Tools & Scripts

• /scripts/ - Utility scripts for common tasks
• /infrastructure/ - Infrastructure as Code
• /tests/ - Test suites

Getting Help

• Check the documentation
• Review troubleshooting guide
• Explore existing issues in the repository

Development Tips

Hot Reload

• Frontend: Runs with hot reload by default (React)
• Backend: Use Tilt for automatic reload on code changes
• Database: Mount volumes for persistent data during development

Testing

# Run all tests
docker-compose exec <service-name> pytest

# Run specific test
docker-compose exec <service-name> pytest tests/test_specific.py

# With coverage
docker-compose exec <service-name> pytest --cov=app tests/

Code Quality

# Format code
black services/auth/app

# Lint code
flake8 services/auth/app

# Type checking
mypy services/auth/app

Performance Optimization

For Development

• Use Tilt for faster iteration
• Enable caching in Docker builds
• Use local volumes instead of named volumes
• Limit resource allocation in Docker Desktop settings

For Production

• See the Deployment Guide
• Configure proper resource limits
• Enable horizontal pod autoscaling
• Use production-grade databases

---

Welcome to Bakery IA! If you have any questions, check the documentation or reach out to the team.

Last Updated: 2025-11-04