Hugging Face's logo

Spaces:
kamau1
/
swiftops-backend
Sleeping

App Files Community
swiftops-backend / docs /api /platform-admin /README.md
kamau1's picture
kamau1
feat: add audit logs and dashboard analytics endpoints
c1ba75f
preview code
|
raw
history blame contribute delete
5.55 kB

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 

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

API Testing 

# 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 

# 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 

# 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