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

   git clone <repository-url>
   cd saas-platform
   

2. Install Docker and Docker Compose

   # Verify Docker installation
   docker --version
   docker-compose --version
   

3. Environment Configuration

   # Copy environment template
   cp .env.template .env
   
   # Edit environment variables
   nano .env
   

Quick Start with Docker

1. Start Development Environment

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

# View logs
docker-compose logs -f

2. Initialize Database

# 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

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Local Development Setup

Backend Development

1. Setup Python Virtual Environment

   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

   # 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

   # Start development server
   python manage.py runserver
   
   # Run with hot reload
   python manage.py runserver --noreload
   

Frontend Development

1. Setup Node.js Environment

   cd frontend
   npm install
   

2. Environment Configuration

   cp .env.template .env.local
   # Edit environment variables
   

3. Run Frontend Development Server

   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

   # Navigate to Retail section
   # Click "Products" → "Add Product"
   # Fill product details and save
   

2. Create Sale

   # Navigate to Point of Sale
   # Add products to cart
   # Select payment method
   # Complete sale
   

3. Check Inventory

   # View stock levels
   # Set reorder points
   # Monitor low stock alerts
   

Healthcare Module Quick Start

1. Register Patients

   # Navigate to Healthcare → Patients
   # Click "Add Patient"
   # Fill medical information
   # Save patient record
   

2. Schedule Appointments

   # Navigate to Appointments
   # Select date and time
   # Choose patient and doctor
   # Set appointment type
   # Confirm booking
   

Education Module Quick Start

1. Add Students

   # Navigate to Education → Students
   # Click "Add Student"
   # Fill student details
   # Link parent account
   # Save record
   

2. Create Classes

   # Navigate to Classes
   # Click "Add Class"
   # Set schedule and teacher
   # Add students to class
   # Save class
   

Testing

Run Test Suite

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

# Integration tests
docker-compose exec backend pytest integration/

API Testing

# 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

   # Production environment
   cp .env.production .env
   
   # Update production settings
   # Set DEBUG=False
   # Configure production database
   # Set up SSL certificates
   

2. Build and Deploy

   # 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

   # Check database status
   docker-compose ps postgres
   
   # Restart database
   docker-compose restart postgres
   
   # Check logs
   docker-compose logs postgres
   

2. Backend Server Issues

   # 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

   # Clear node modules
   rm -rf node_modules package-lock.json
   
   # Reinstall dependencies
   npm install
   
   # Rebuild frontend
   npm run build
   

Port Conflicts

# 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! 🚀