Skip to content

Admin API Overview

The Admin API serves as the backend service for the Admin Dashboard, providing comprehensive management and monitoring capabilities for the AngelCX AI agent platform. This service enables administrators to customize AI behavior, manage content, view analyzed conversations, and integrate with third-party services.

Core Functionalities

Authentication

  • Through Cognito middleware

AI Agent Management

  • Customization of AI agent behavior and responses
  • Configuration of conversation parameters
  • Management of agent's knowledge base
  • UI customization settings

Analytics and Monitoring

  • Conversation analytics and metrics
  • Visitor interaction history
  • Performance monitoring
  • Usage statistics

RAG (Retrieval Augmented Generation)

  • Integration with Ultravox APIs for RAG management
  • Document ingestion and processing
  • Knowledge base updates
  • Vector store management

Payment Processing

  • Stripe webhook handling
  • Subscription management
  • Billing integration
  • Payment status tracking

Third-Party Integrations

  • HubSpot, Calendly, etc.
  • OAuth flow management
  • API key management

Post-Session Management

  • Email configuration for post session emails

Project Structure

graph TD A[Main Application] --> B[Feature Modules] A --> C[Database Layer] A --> D[Middleware] B --> BA[Agent Module] B --> BB[Conversations] B --> BC[Customer Management] B --> BD[RAG] B --> BE[Third-Party Apps] C --> CA[SQLModel Definitions] C --> CB[Database Client] D --> DA[Cognito Auth]

Directory Organization

angel-saas-admin-api/
├── app/
│   ├── agent/               # Agent customization and management
│   ├── conversations/       # Conversation handling
│   ├── customer/           # Customer data management
│   ├── rag/               # RAG operations
│   ├── third_party_app/   # External integrations
│   ├── db/                # Database layer
│   ├── middleware/        # Auth and request processing
│   └── main.py           # Application entry point

Authentication and Security

The Admin API implements secure authentication using Amazon Cognito:

sequenceDiagram participant Client participant AdminAPI participant Cognito participant Database Client->>AdminAPI: API Request + Token AdminAPI->>Cognito: Validate Token Cognito-->>AdminAPI: Token Valid AdminAPI->>Database: Authorized Query Database-->>AdminAPI: Data AdminAPI-->>Client: Response

Integration Points

  • Admin Dashboard: Primary frontend client
  • Ultravox: For RAG management
  • Stripe: Payment processing
  • Cognito: Authentication
  • Third-party Services: HubSpot, Calendly, etc.

API Structure

Each feature module follows a consistent pattern:

  1. Router Layer (router.py)

    • API endpoint definitions
    • Request/response handling
    • Route protection

  2. Service Layer (service.py)

    • Business logic implementation
    • External service integration
    • Data processing

  3. Model Layer (model.py)

    • Data schemas
    • Type definitions
    • Validation rules

  4. Database Layer (db_helper.py)

    • Database operations
    • Query handling
    • Data persistence

Development and Deployment

Local Development

  • Python 3.12 environment
  • FastAPI development server
  • Swagger documentation at /docs
  • Local testing environment

Production Deployment

  • Containerized deployment
  • AWS infrastructure
  • Automated CI/CD pipeline
  • Monitoring and logging

Best Practices

  1. Authentication

    • Try to secure all endpoints with Cognito tokens to ensure no admin operation is publicly accessible
    • Token validation middleware

  2. Error Handling

    • Consistent error responses
    • Detailed error logging
    • Client-friendly error messages

  3. Data Validation

    • Pydantic models for request/response
    • Input sanitization
    • Type checking

  4. Performance

    • Async database operations
    • Connection pooling
    • Query optimization

  5. Security

    • CORS configuration
    • Rate limiting planned through API gateway
    • Input validation through Pydantic
    • Secure headers