project initialization

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

@@ -0,0 +1,360 @@
+# 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! 🚀