docs/api/platform-admin/README.md

# API Documentation

This folder contains frontend development guides for the SwiftOps platform.

---

## 📚 Available Guides

### 1. Platform Admin Frontend Guide
**File:** `PLATFORM_ADMIN_FRONTEND_GUIDE.md`  
**Purpose:** Comprehensive guide for building platform admin frontend  
**Audience:** Frontend developers

**Contents:**
- Complete API reference
- Dashboard & analytics implementation
- Organization management (clients & contractors)
- User management
- System monitoring
- Audit logs
- UI/UX recommendations
- Error handling patterns
- Code examples

**When to use:** Reference this when building any platform admin feature

---

### 2. Platform Admin Quick Reference
**File:** `PLATFORM_ADMIN_QUICK_REFERENCE.md`  
**Purpose:** Quick reference for common tasks  
**Audience:** Frontend developers who need fast answers

**Contents:**
- Essential API endpoints
- Quick request/response examples
- Form validations
- Error handling
- Common patterns
- Testing credentials

**When to use:** Quick lookups during development

---

## 🚀 Getting Started

### Step 1: Authentication
1. Implement login page
2. Setup token storage
3. Create API service layer

### Step 2: Dashboard
1. Create layout with navigation
2. Add statistics cards
3. Implement recent activity feed

### Step 3: Organizations
1. Build clients management pages
2. Build contractors management pages
3. Add create/edit forms

### Step 4: Users & Monitoring
1. Build users list and management
2. Add audit logs page
3. Implement exports

---

## 🔗 Related Documentation

### Backend Documentation
- **Organizations API:** `/docs/dev/ORGANIZATIONS_API_GUIDE.md`
- **Auth API:** `/docs/dev/AUTH_API_GUIDE.md`
- **User Management:** `/docs/USER_MANAGEMENT_IMPLEMENTATION.md`
- **Audit Logging:** `/docs/agent/PASSWORD_RESET_COMPLETE.md`

### API Documentation
- **Interactive Docs:** `http://localhost:8000/api/docs` (Swagger UI)
- **Alternative Docs:** `http://localhost:8000/api/redoc` (ReDoc)
- **Health Check:** `http://localhost:8000/health`

---

## 🛠️ Development Environment

### Backend Setup
```bash
# Start backend server
cd d:\atomio\swiftops-backend
python -m uvicorn app.main:app --reload --port 8000
```

### API Testing
```bash
# Test with cURL
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@swiftops.com","password":"your-password"}'
```

### Environment Variables
```bash
# Backend .env
PLATFORM_ADMIN_EMAIL=admin@swiftops.com
RESEND_API_KEY=re_xxxxxxxxxxxxx
DATABASE_URL=postgresql://...
SUPABASE_URL=https://...
SUPABASE_KEY=...
```

---

## 📋 Implementation Checklist

### Core Features
- [ ] Authentication (login, registration, logout)
- [ ] Dashboard with statistics
- [ ] Clients management (CRUD)
- [ ] Contractors management (CRUD)
- [ ] Users management
- [ ] User invitations
- [ ] Audit logs viewing
- [ ] Data export functionality

### UI/UX
- [ ] Responsive design (mobile, tablet, desktop)
- [ ] Loading states
- [ ] Error handling
- [ ] Success notifications
- [ ] Confirmation dialogs
- [ ] Pagination
- [ ] Search/filtering
- [ ] Sorting

### Quality
- [ ] Unit tests
- [ ] Integration tests
- [ ] Accessibility (WCAG 2.1)
- [ ] Performance optimization
- [ ] Code documentation
- [ ] API error handling

---

## 🎨 Design System

### Colors
- **Primary:** `#2563eb` (Blue)
- **Success:** `#10b981` (Green)
- **Warning:** `#f59e0b` (Amber)
- **Danger:** `#ef4444` (Red)
- **Info:** `#3b82f6` (Blue)
- **Platform Admin:** `#8b5cf6` (Purple)

### Typography
- **Font:** Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto
- **Heading 1:** 32px, 700 weight
- **Heading 2:** 24px, 600 weight
- **Heading 3:** 18px, 600 weight
- **Body:** 14px, 400 weight

### Spacing
- **xs:** 4px
- **sm:** 8px
- **md:** 16px
- **lg:** 24px
- **xl:** 32px
- **2xl:** 48px

---

## 🐛 Common Issues

### Issue: 401 Unauthorized
**Solution:** Token expired. Implement token refresh or redirect to login.

### Issue: CORS errors
**Solution:** Backend CORS is configured. Check if you're using correct API URL.

### Issue: 409 Conflict (duplicate email/name)
**Solution:** Show validation error. Email/name must be unique.

### Issue: Slow page loads
**Solution:** Implement pagination, lazy loading, and caching.

---

## 📞 Support

### Questions?
- **Backend Team:** Check `/docs` folder for implementation details
- **API Issues:** Review `http://localhost:8000/api/docs`
- **Bug Reports:** Check audit logs for detailed error traces

### Useful Commands
```bash
# View recent audit logs
curl http://localhost:8000/api/v1/audit-logs?limit=20 \
  -H "Authorization: Bearer {token}"

# Test client creation
curl -X POST http://localhost:8000/api/v1/clients \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test Client","main_email":"test@example.com"}'

# Check health
curl http://localhost:8000/health
```

---

## 📝 Contributing

When adding new documentation:

1. **Name files clearly:** Use `FEATURE_NAME_GUIDE.md` or `FEATURE_NAME_REFERENCE.md`
2. **Include examples:** Always provide request/response examples
3. **Add to README:** Update this file with new documentation
4. **Keep it updated:** Update docs when API changes

---

## 📊 API Versioning

Current version: **v1**  
Base URL: `/api/v1`

All endpoints are prefixed with `/api/v1`. When v2 is released, v1 will continue to work for backward compatibility.

---

**Last Updated:** November 17, 2025  
**Maintained By:** SwiftOps Backend Team