Skip to main content

Core Concepts

Taruvi Cloud is organized into three levels: Organizations, Sites, and Apps. Understanding this hierarchy is essential to working with the platform.

Organizations​

An Organization is the top-level entity in Taruvi — it represents your company or team.

An organization owns:

  • Members with roles (owner, admin, member)
  • Sites that contain your apps and data
  • Billing and subscription management

Every Taruvi account belongs to at least one organization. You can create multiple organizations to separate unrelated projects or clients.

See Cloud Console: Organizations for managing organizations through the web UI.

Sites​

A Site is an isolated cloud environment within an organization. Each site has its own:

  • Apps containing your backend resources
  • Domains (custom domains can point to a site)
  • Users (each site has a separate user base)
  • Site-level secrets (encrypted configuration)
  • Frontend workers for edge logic

Sites provide complete data isolation — data in one site is invisible to every other site. This makes sites ideal for separating production from staging, or isolating customer data in a multi-tenant product.

Environment typePurpose
ProductionLive customer-facing environment
StagingPre-release testing and QA
DevelopmentActive development and experimentation
TestingAutomated test environments

See Cloud Console: Sites for managing sites through the web UI.

Apps​

An App is a container within a site that groups backend resources together. Each app can contain:

  • Datatables — Structured data storage with schemas, querying, and relationships
  • Functions — Serverless code execution and webhook proxies
  • Storage — File buckets with access controls
  • Roles & Policies — Custom authorization rules
  • Secrets — Encrypted app-level configuration
  • Events — Event subscriptions for triggering workflows
  • Analytics — Parameterized query templates

Apps let you organize your backend by feature or domain. For example, an e-commerce platform might have a "Store" app for products and orders, and a "CMS" app for content management.

See Sites & Apps for a detailed breakdown of what each app includes, and Cloud Console: Apps for managing apps through the web UI.

Authentication​

Taruvi uses JWT tokens scoped to a site. When a user authenticates, they receive access and refresh tokens that grant access to the apps within that site.

The SDKs handle authentication automatically — you sign in once and all subsequent requests include the token.

For details, see SDK Authentication and User Management.

Accessing Your Backend​

There are four ways to interact with Taruvi:

MethodDescriptionReference
Taruvi ConsoleWeb UI for managing organizations, sites, apps, and dataCloud Console
REST APIHTTP endpoints for all platform operationsAPI Reference
SDKsPython and JavaScript clients with type-safe interfacesSDK Overview
MCPConnect AI tools directly to your Taruvi backendMCP Integration
from taruvi import Client

# Create and authenticate
client = Client(api_url="http://localhost:8000", app_slug="my-app")
auth_client = client.auth.signInWithPassword(
    username="[email protected]",
    password="admin"
)

# Query database
users = auth_client.database.from_("users").page_size(10).execute()
print(f"Found {len(users)} users")

# Execute function
result = auth_client.functions.execute("my-function", params={"test": True})
print(result['data'])

Installation:

pip install taruvi

SDK Features:

  • ✅ Type-safe API with full IDE autocomplete
  • ✅ Async and sync support
  • ✅ Query builder for complex queries
  • ✅ Automatic retry and error handling
  • ✅ Connection pooling for better performance

See the complete Python SDK Documentation for detailed guides and examples.

Background Tasks​

Taruvi uses Celery for background processing:

# Start Celery worker (if not using Docker)
celery -A taruvi_project worker --loglevel=info

# Start Celery beat scheduler
celery -A taruvi_project beat --loglevel=info

# Monitor tasks in Django admin
# Visit /admin/django_celery_results/taskresult/

Health Monitoring​

Check application health:

# JSON health check
curl http://localhost:8000/health/?format=json

# Plain text check
curl http://localhost:8000/health/

Health check includes:

  • Database connectivity
  • Cache availability
  • Storage access
  • Celery worker status

Next Steps​