Skip to main content

Hasura Integration & Configuration

Hasura GraphQL Engine serves as the core data layer for the Comdeall platform, providing instant GraphQL APIs over PostgreSQL with sophisticated authorization, real-time subscriptions, and custom business logic integration. The integration follows a hybrid architecture where Hasura handles data operations while NestJS backend provides complex business logic through actions and functions.

Table of Contents​

  1. Architecture Overview
  2. Docker Configuration
  3. Database Configuration
  4. Actions System
  5. Custom Functions
  6. Custom Types & Enums
  7. Authorization & Permissions
  8. Metadata Management
  9. Environment Configuration
  10. Security Implementation
  11. Best Practices
  12. Conclusion

Architecture Overview​

Hybrid GraphQL Architecture​

Comdeall implements a hybrid architecture combining Hasura's instant GraphQL capabilities with NestJS custom business logic:

Frontend Applications (Mobile/Admin) ↓ Hasura GraphQL Engine ├── Direct Database Queries (CRUD) ├── Custom Actions → NestJS Backend └── Database Functions ↓ PostgreSQL Database

Architecture Benefits:

  • Instant GraphQL: Auto-generated GraphQL schema from database
  • Real-time Capabilities: Built-in subscriptions for live data updates
  • Custom Business Logic: Complex operations handled by NestJS actions
  • Type Safety: End-to-end type safety from database to frontend
  • Performance: Optimized queries with automatic query planning

Service Integration​

Hasura integrates seamlessly with the containerized infrastructure:

Service Dependencies:

  • PostgreSQL: Primary database for all application data
  • NestJS Backend: Custom business logic and external integrations
  • Authentication: JWT-based authentication with custom claims

Docker Configuration​

Hasura Container Setup​

Hasura runs as a containerized service with specific version and configuration:

hasura-graphql:
  container_name: "hasura-graphql"
  image: hasura/graphql-engine:v2.20.0
  env_file:
    - .env
  ports:
    - "8080:8080"
  depends_on:
    - "postgres-db"
  restart: always
  networks:
    - comedeall

Configuration Features:

  • Version Pinning: Uses Hasura v2.20.0 for stability and feature compatibility
  • Environment Integration: Shares environment variables with other services
  • Network Isolation: Runs on dedicated Docker network for security
  • Auto-restart: Ensures high availability with automatic restart policy
  • Database Dependency: Waits for PostgreSQL to be ready before starting

Network Architecture​

Hasura participates in the microservices network architecture:

Network Configuration:

  • Internal Network: comedeall network for service communication
  • Port Exposure: GraphQL endpoint exposed on port 8080
  • Service Discovery: Accessible to other services via container name
  • Load Balancing: Ready for load balancing and scaling configurations

Database Configuration​

Primary Database Connection​

Hasura connects to the main PostgreSQL database with optimized settings:

- name: comdeall
  kind: postgres
  configuration:
    connection_info:
      database_url:
        from_env: HASURA_GRAPHQL_DATABASE_URL
      isolation_level: read-committed
      use_prepared_statements: false
    tables: "!include comdeall/tables/tables.yaml"
    functions: "!include comdeall/functions/functions.yaml"

Database Features:

  • Environment-based URL: Database connection from environment variables
  • Read-committed Isolation: Optimal isolation level for web applications
  • Prepared Statements: Disabled for better compatibility with connection pooling
  • Modular Configuration: Separate files for tables and functions management

Table and Schema Management​

Database schema is managed through Hasura's metadata system:

Schema Organization:

  • Table Definitions: Comprehensive table configuration with relationships
  • Function Definitions: Custom PostgreSQL functions exposed as GraphQL
  • Permission Rules: Row-level security and column-level permissions
  • Relationship Mapping: Automatic and custom relationship definitions

Actions System​

Action Architecture​

Hasura actions provide seamless integration with NestJS backend for complex business logic:

Action Configuration:

actions:
  - name: actionName
    definition:
      kind: synchronous
      handler: http://webserver/api/endpoint
      forward_client_headers: true
      timeout: 180
    permissions:
      - role: PARENT
      - role: THERAPIST

Action Categories:

Authentication Actions​

  • Social Authentication: Google, Facebook, Apple OAuth integration
  • OTP Management: Send and verify OTP for email/phone authentication
  • Token Management: Access token renewal and device token registration
  • Admin Authentication: Secure admin login and registration

User Management Actions​

  • Parent Operations: Create parent accounts, child management
  • Therapist Operations: Therapist approval, profile management
  • Child Management: Add, edit, and manage child profiles
  • Account Operations: User deletion, status management

Appointment Management Actions​

  • Appointment Lifecycle: Create, approve, reschedule, cancel appointments
  • Payment Integration: Appointment payment processing and confirmation
  • Scheduling: Advanced scheduling with therapist availability
  • Notifications: Automated appointment notifications and reminders

Subscription Management Actions​

  • Plan Management: Create, update, disable subscription plans
  • Payment Processing: Razorpay and iOS subscription handling
  • Subscription Lifecycle: Create, update, cancel subscriptions
  • Multi-platform Support: iOS App Store and Android integration

Assessment & Content Actions​

  • Assessment Management: Create, update, assign assessments
  • Question Management: Dynamic question and option handling
  • Content Management: FAQ, terms, privacy policy management
  • Report Generation: Automated assessment report creation

Action Features​

Advanced Configuration:

  • Timeout Management: Custom timeouts for long-running operations
  • Header Forwarding: Client headers passed to backend for context
  • Request Transformation: Query parameter mapping and header manipulation
  • Permission Matrix: Role-based access control for each action

Custom Functions​

Database Function Integration​

PostgreSQL functions are exposed as GraphQL mutations with sophisticated logic:

Function Categories:

Child Management Functions​

  • add_child: Comprehensive child addition with validation
  • edit_child: Child profile updates with business rules
  • parent_onboarding: Complete parent onboarding workflow

Appointment Functions​

  • appointment_reschedule_request: Advanced rescheduling logic
  • transfer_appointment_fee: Financial transaction management
  • create_therapist_schedule: Schedule creation with conflict detection

Assessment Functions​

  • assign_lesson_plans_to_child: Intelligent lesson plan assignment
  • capture_lesson_plan_progress: Progress tracking with analytics

Content Management Functions​

  • create_support_ticket: Support ticket creation with routing
  • create_content: Content management with versioning
  • create_faq: FAQ management with categorization

Function Configuration​

Database functions are configured with specific permissions and session context:

function:
  name: function_name
  schema: public
configuration:
  exposed_as: mutation
  session_argument: hasura_session
permissions:
  - role: PARENT
  - role: ADMIN

Function Features:

  • Session Context: Access to user session and JWT claims
  • Role-based Permissions: Granular access control per function
  • Mutation Exposure: Functions exposed as GraphQL mutations
  • Business Logic: Complex database operations with validation

Custom Types & Enums​

Comprehensive Type System​

Hasura includes extensive custom types and enums for type-safe operations:

Core Enums:

  • User Types: role (ADMIN, THERAPIST, PARENT)
  • Assessment Types: assessmentType (CASE_HISTORY, SCREENING, CDDC, PLS, ORO)
  • Appointment Types: AppointmentType (ONE_ON_ONE, TEAM_MEETING)
  • Transaction Types: TransactionType (APPOINTMENT, SUBSCRIPTION, PAYOUT)
  • Subscription Types: subscription_type (MONTHLY, YEARLY)

Business Logic Enums:

  • Approval Status: approval_status (APPROVED, REJECTED, PENDING)
  • Lesson Types: Comprehensive therapy domain categories
  • Progress Status: ChildLessonPlanProgressStatus (NOT_STARTED, IN_PROGRESS, COMPLETED)
  • Platform Types: device_platform (IOS, ANDROID)

Input/Output Objects:

  • Authentication: Social auth inputs, OTP verification objects
  • User Management: Parent creation, child management inputs
  • Appointments: Scheduling, payment, and management objects
  • Subscriptions: Plan management and payment confirmation objects

Type Safety Benefits​

End-to-End Type Safety:

  • Frontend Integration: Auto-generated TypeScript types for frontends
  • API Consistency: Consistent data structures across all operations
  • Validation: Built-in validation through GraphQL schema
  • Documentation: Self-documenting API with type definitions

Authorization & Permissions​

Role-Based Access Control​

Comprehensive permission system based on user roles:

Role Hierarchy:

  • PUBLIC: Unauthenticated access (registration, login)
  • PARENT: Parent-specific operations and child management
  • THERAPIST: Therapy-related operations and appointments
  • ADMIN: Full system access and management operations

Permission Matrix​

Each action and table operation has specific role permissions:

Permission Features:

  • Granular Control: Column-level and row-level permissions
  • Context-aware: Permissions based on user context and relationships
  • Dynamic Rules: Permissions that adapt based on data relationships
  • Audit Trail: Complete access logging and permission tracking

JWT Integration​

Authentication integration with custom JWT claims:

JWT Claims Structure:

{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "PARENT",
    "x-hasura-allowed-roles": ["PARENT"],
    "x-hasura-user-id": "user-uuid",
    "x-hasura-parent-id": "parent-uuid",
    "x-hasura-therapist-id": "therapist-uuid"
  }
}

Metadata Management​

Version Control Integration​

Hasura metadata is version-controlled for consistency across environments:

Metadata Structure:

hasura/metadata/ ├── actions.yaml # Action definitions and permissions ├── databases/ │ └── comdeall/ │ ├── functions/ # Database function configurations │ └── tables/ # Table permissions and relationships ├── version.yaml # Hasura version specification └── .yaml # Additional configuration files

Management Features:

  • Environment Consistency: Same metadata across dev, staging, production
  • Change Tracking: Git-based change tracking for all modifications
  • Migration Safety: Controlled metadata updates and rollbacks
  • Team Collaboration: Shared metadata configuration for team development

Configuration Files​

Core Configuration Files:

  • config.yaml: Hasura CLI configuration with endpoints
  • actions.yaml: Complete action definitions with permissions
  • databases.yaml: Database connection and configuration
  • version.yaml: Hasura version specification

Environment Configuration​

Environment Variables​

Hasura configuration through environment variables:

Core Variables:

# Database Connection
HASURA_GRAPHQL_DATABASE_URL=postgresql://user:pass@host:port/db

# Authentication
HASURA_GRAPHQL_JWT_SECRET={"type":"HS256","key":"secret"}
HASURA_GRAPHQL_ADMIN_SECRET=admin-secret

# Features
HASURA_GRAPHQL_ENABLE_CONSOLE=true
HASURA_GRAPHQL_DEV_MODE=false
HASURA_GRAPHQL_ENABLED_LOG_TYPES=startup,http-log,webhook-log

Action Integration:

  • Webhook Base URL: Backend service URL for action handlers
  • Header Forwarding: Client headers passed to backend services
  • Environment Awareness: Different configurations per environment

Security Implementation​

Security Layers​

Multiple security layers protect the GraphQL API:

Security Features:

  • JWT Authentication: Secure token-based authentication
  • Role-based Authorization: Granular permissions per user role
  • Admin Secret: Administrative access protection
  • CORS Configuration: Cross-origin request control
  • Rate Limiting: Protection against abuse and DDoS

Best Practices Implementation​

Security Best Practices:

  • Principle of Least Privilege: Minimal permissions per role
  • Secure Defaults: Restrictive default permissions
  • Audit Logging: Complete access and operation logging
  • Environment Isolation: Separate configurations per environment

Best Practices​

Development Workflow​

Optimal development practices for Hasura integration:

Development Guidelines:

  • Metadata Version Control: All changes tracked in Git
  • Environment Parity: Consistent configuration across environments
  • Testing Strategy: Comprehensive testing of actions and functions
  • Migration Safety: Careful schema and metadata migrations

Performance Optimization​

Performance best practices for GraphQL operations:

Optimization Strategies:

  • Query Analysis: Monitor and optimize expensive queries
  • Connection Pooling: Efficient database connection management
  • Caching Strategy: Appropriate caching for frequently accessed data
  • Subscription Optimization: Efficient real-time subscription management

Monitoring and Observability​

Comprehensive monitoring for production operations:

Monitoring Practices:

  • Query Performance: Monitor GraphQL query execution times
  • Error Tracking: Comprehensive error logging and alerting
  • Resource Usage: Database and system resource monitoring
  • Security Monitoring: Authentication and authorization audit logs

Conclusion​

Hasura integration in the Comdeall platform provides a powerful, type-safe, and scalable GraphQL API layer that seamlessly combines instant database APIs with custom business logic. Key strengths include:

Comprehensive GraphQL API:

  • Instant Database APIs: Auto-generated GraphQL schema with full CRUD operations
  • Custom Business Logic: Seamless integration with NestJS backend for complex operations
  • Real-time Capabilities: Built-in subscriptions for live data updates
  • Type Safety: End-to-end type safety from database to frontend applications

Production-Ready Features:

  • Role-based Security: Comprehensive authorization with granular permissions
  • Docker Integration: Containerized deployment with proper service dependencies
  • Metadata Management: Version-controlled configuration for consistent environments
  • Performance Optimization: Optimized queries and connection management

Scalable Architecture:

  • Hybrid Approach: Best of both worlds with instant APIs and custom logic
  • Multi-platform Support: Consistent API for mobile and web applications
  • Extension Points: Easy addition of new actions and functions
  • Team Collaboration: Shared metadata and development workflows

The Hasura integration enables rapid development of GraphQL APIs while maintaining the flexibility to implement complex business logic, making it an ideal solution for the comprehensive therapy management platform serving parents, therapists, and administrators.