multitenetsaas/specs/001-1-target-sectors/quickstart.md

# Quickstart Guide

## Prerequisites

### System Requirements
- **Operating System**: Linux, macOS, or Windows (with WSL2)
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
- **Python**: 3.11+ (for local development)
- **Node.js**: 18+ (for frontend development)
- **PostgreSQL**: 14+ (for local database)

### Development Environment Setup
1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd saas-platform
   ```

2. **Install Docker and Docker Compose**
   ```bash
   # Verify Docker installation
   docker --version
   docker-compose --version
   ```

3. **Environment Configuration**
   ```bash
   # Copy environment template
   cp .env.template .env

   # Edit environment variables
   nano .env
   ```

## Quick Start with Docker

### 1. Start Development Environment
```bash
# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f
```

### 2. Initialize Database
```bash
# Run database migrations
docker-compose exec backend python manage.py migrate

# Create superuser
docker-compose exec backend python manage.py createsuperuser

# Load initial data
docker-compose exec backend python manage.py load_initial_data
```

### 3. Access Applications
- **Backend API**: http://localhost:8000
- **Frontend**: http://localhost:3000
- **Admin Dashboard**: http://localhost:8000/admin
- **API Documentation**: http://localhost:8000/api/docs

### 4. Stop Environment
```bash
# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v
```

## Local Development Setup

### Backend Development

1. **Setup Python Virtual Environment**
   ```bash
   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

   # Install dependencies
   pip install -r requirements.txt
   ```

2. **Database Setup**
   ```bash
   # Start PostgreSQL
   docker run --name postgres-dev -e POSTGRES_PASSWORD=devpass -p 5432:5432 -d postgres:14

   # Create database
   createdb saas_platform_dev

   # Run migrations
   python manage.py migrate

   # Create superuser
   python manage.py createsuperuser
   ```

3. **Run Backend Server**
   ```bash
   # Start development server
   python manage.py runserver

   # Run with hot reload
   python manage.py runserver --noreload
   ```

### Frontend Development

1. **Setup Node.js Environment**
   ```bash
   cd frontend
   npm install
   ```

2. **Environment Configuration**
   ```bash
   cp .env.template .env.local
   # Edit environment variables
   ```

3. **Run Frontend Development Server**
   ```bash
   npm run dev
   ```

## First Steps

### 1. Create Your First Tenant
1. Access the admin dashboard: http://localhost:8000/admin
2. Login with your superuser credentials
3. Navigate to "Tenants" section
4. Click "Add Tenant" and fill in the details:
   - **Name**: Your business name
   - **Email**: Business email
   - **Business Type**: Select industry
   - **Subscription Plan**: Choose appropriate plan

### 2. Create User Accounts
1. In admin dashboard, navigate to "Users"
2. Click "Add User" and create users for your tenant
3. Assign appropriate roles (Admin, Manager, Staff, Viewer)

### 3. Activate Modules
1. Navigate to tenant's subscription
2. Select modules to activate:
   - **Retail**: For stores and food stalls
   - **Healthcare**: For clinics and medical practices
   - **Education**: For tuition centers
   - **Logistics**: For delivery companies
   - **Beauty**: For salons and spas

### 4. Access Tenant Portal
1. Open frontend application: http://localhost:3000
2. Login with tenant-specific URL: `http://localhost:3000/{tenant-slug}`
3. Use credentials created in step 2

## Module Setup Guides

### Retail Module Quick Start
1. **Add Products**
   ```bash
   # Navigate to Retail section
   # Click "Products" → "Add Product"
   # Fill product details and save
   ```

2. **Create Sale**
   ```bash
   # Navigate to Point of Sale
   # Add products to cart
   # Select payment method
   # Complete sale
   ```

3. **Check Inventory**
   ```bash
   # View stock levels
   # Set reorder points
   # Monitor low stock alerts
   ```

### Healthcare Module Quick Start
1. **Register Patients**
   ```bash
   # Navigate to Healthcare → Patients
   # Click "Add Patient"
   # Fill medical information
   # Save patient record
   ```

2. **Schedule Appointments**
   ```bash
   # Navigate to Appointments
   # Select date and time
   # Choose patient and doctor
   # Set appointment type
   # Confirm booking
   ```

### Education Module Quick Start
1. **Add Students**
   ```bash
   # Navigate to Education → Students
   # Click "Add Student"
   # Fill student details
   # Link parent account
   # Save record
   ```

2. **Create Classes**
   ```bash
   # Navigate to Classes
   # Click "Add Class"
   # Set schedule and teacher
   # Add students to class
   # Save class
   ```

## Testing

### Run Test Suite
```bash
# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

# Integration tests
docker-compose exec backend pytest integration/
```

### API Testing
```bash
# Import Postman collection
# File: docs/api/SaaS_Platform.postman_collection.json

# Or use curl examples
curl -X GET "http://localhost:8000/api/v1/tenants/" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Deployment

### Production Deployment
1. **Environment Configuration**
   ```bash
   # Production environment
   cp .env.production .env

   # Update production settings
   # Set DEBUG=False
   # Configure production database
   # Set up SSL certificates
   ```

2. **Build and Deploy**
   ```bash
   # Build production images
   docker-compose -f docker-compose.prod.yml build

   # Deploy to production
   docker-compose -f docker-compose.prod.yml up -d
   ```

### Cloud Deployment Options
- **AWS**: ECS Fargate with RDS
- **Google Cloud**: Cloud Run with Cloud SQL
- **Azure**: Container Instances with Database
- **Malaysian Cloud**: MYNIC, EXABYTE, or TM One

## Troubleshooting

### Common Issues

1. **Database Connection Issues**
   ```bash
   # Check database status
   docker-compose ps postgres

   # Restart database
   docker-compose restart postgres

   # Check logs
   docker-compose logs postgres
   ```

2. **Backend Server Issues**
   ```bash
   # Check backend logs
   docker-compose logs backend

   # Restart backend
   docker-compose restart backend

   # Check database migrations
   docker-compose exec backend python manage.py showmigrations
   ```

3. **Frontend Build Issues**
   ```bash
   # Clear node modules
   rm -rf node_modules package-lock.json

   # Reinstall dependencies
   npm install

   # Rebuild frontend
   npm run build
   ```

### Port Conflicts
```bash
# Check port usage
lsof -i :8000
lsof -i :3000
lsof -i :5432

# Kill processes using ports
kill -9 <PID>
```

## Support

### Documentation
- **API Documentation**: http://localhost:8000/api/docs
- **Admin Guide**: docs/admin-guide.md
- **Module Documentation**: docs/modules/
- **Deployment Guide**: docs/deployment.md

### Getting Help
- **Issues**: GitHub Issues
- **Discussions**: GitHub Discussions
- **Email**: support@saas-platform.com
- **Community**: Discord community channel

### Contributing
1. Fork the repository
2. Create feature branch
3. Make your changes
4. Add tests
5. Submit pull request

## Next Steps

1. **Explore Modules**: Try out different industry modules
2. **Customize Branding**: Upload your logo and customize colors
3. **Set Up Payment**: Configure payment processors
4. **Add Users**: Invite team members
5. **Configure Notifications**: Set up email/SMS notifications
6. **Explore Reports**: Check out analytics and reporting

Happy building! 🚀