bakery-ia/docs/01-getting-started/README.md

# 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

```bash
git clone <repository-url>
cd bakery-ia
```

### 2. Set Up Environment Variables

```bash
# 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

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

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

### 4. Verify the Deployment

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Restart a Service

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

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

### Access Database

```bash
# 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

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

### Clean Up

```bash
# 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

```bash
# 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](../02-architecture/system-overview.md)** - Understand the system design
2. **[Development Workflow](../04-development/README.md)** - Learn development best practices
3. **[API Reference](../08-api-reference/README.md)** - Explore available APIs
4. **[Deployment Guide](../05-deployment/README.md)** - Deploy to production

## Additional Resources

### Documentation
- [Testing Guide](../04-development/testing-guide.md)
- [Security Overview](../06-security/README.md)
- [Feature Documentation](../03-features/)

### Tools & Scripts
- `/scripts/` - Utility scripts for common tasks
- `/infrastructure/` - Infrastructure as Code
- `/tests/` - Test suites

### Getting Help

- Check the [documentation](../)
- Review [troubleshooting guide](#troubleshooting)
- 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

```bash
# 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

```bash
# 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](../05-deployment/README.md)
- 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