Improve AI logic
This commit is contained in:
Urtzi Alfaro
378
docs/01-getting-started/README.md
Normal file
378
docs/01-getting-started/README.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user