# ⚡ Quick Start Guide - Apex SaaS Framework

Get your SaaS application running in 5 minutes!

---

## 1️⃣ Install Package

**Simple installation from PyPI:**

```bash
pip install apex-saas-framework
```

That's it! ✅

---

## 2️⃣ Create Project Files

### 📁 Directory Structure
```
my_app/
├── .env
├── models.py
├── app.py
└── requirements.txt
```

### 📝 models.py
```python
from apex.app.models.default import (
    Organization,
    OrganizationLocation,
    Permission,
    Role,
    User,
)

__all__ = ["Organization", "OrganizationLocation", "Permission", "Role", "User"]
```

> To add custom fields, create new subclasses (for example `class CustomerUser(User): ...`)
> and remember to update the dependency overrides to use them. Don’t redeclare the
> stock tables in place—Apex already registers them.

### 🚀 app.py
```python
from fastapi import FastAPI
from apex.core.config import get_settings
from apex.api.v1 import auth_router, users_router, organizations_router
from models import User, Organization, Role, Permission

settings = get_settings()
app = FastAPI(title=settings.APP_NAME)

app.include_router(auth_router, prefix="/api/v1/auth", tags=["Auth"])
app.include_router(users_router, prefix="/api/v1/users", tags=["Users"])
app.include_router(organizations_router, prefix="/api/v1/organizations", tags=["Orgs"])

@app.get("/")
async def root():
    return {"message": "Welcome to your SaaS API!"}
```

### ⚙️ .env
```bash
# Database
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb

# JWT
SECRET_KEY=change-this-super-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Email
EMAIL_PROVIDER=sendgrid
SEND_GRID_API=SG.your-api-key
FROM_EMAIL=noreply@yourdomain.com
FRONTEND_RESET_URL=http://localhost:3000/reset-password

# PayPal
PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-secret
PAYPAL_MODE=sandbox

# CORS
ALLOWED_ORIGINS=http://localhost:3000
```

---

## 3️⃣ Initialize Database

```python
# init_db.py
import asyncio
from apex.infrastructure.database import get_engine
from apex.infrastructure.database.base import Base
from models import User, Organization, Role, Permission

async def init():
    engine = get_engine()
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    print("✅ Database ready!")

asyncio.run(init())
```

Run:
```bash
python init_db.py
```

---

## 4️⃣ Run Application

```bash
uvicorn app:app --reload
```

Visit: **http://localhost:8000/docs**

---

## 5️⃣ Test Authentication

### Sign Up
```bash
curl -X POST "http://localhost:8000/api/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "SecurePass123!",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "country": "US",
    "organization_name": "My Company"
  }'
```

### Login
```bash
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=test@example.com&password=SecurePass123!"
```

You'll get:
```json
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer"
}
```

### Get Current User
```bash
curl -X GET "http://localhost:8000/api/v1/users/me" \
  -H "Authorization: Bearer eyJhbGc..."
```

---

## 🎉 That's It!

You now have:
- ✅ User authentication (signup, login, password reset)
- ✅ Organization management
- ✅ Role-based permissions
- ✅ PayPal integration ready
- ✅ Email functionality
- ✅ Multi-tenant support

---

## 📚 Next Steps

1. **Read Full Guide:** See `USER_GUIDE.md` for complete documentation
2. **Add Custom Fields:** Extend models with your own fields
3. **Setup PayPal:** Configure subscription plans
4. **Deploy:** Use Docker or cloud platform

---

## 🆘 Need Help?

- **API Docs:** http://localhost:8000/docs
- **Full Guide:** `USER_GUIDE.md`
- **Examples:** See `examples/` folder
- **Issues:** https://github.com/yourusername/apex-saas-framework/issues

---

**Happy Building! 🚀**

