Skip to main content

Sites & Apps

This page explains the Taruvi hierarchy in detail — what sites and apps are, what resources each app contains, and when to use sites vs apps to organize your backend.

The Taruvi Hierarchy​

Every Taruvi backend follows the same structure: an Organization contains Sites, and each Site contains Apps.

What is a Site?​

A Site is a fully isolated cloud environment. Each site has its own database, its own user base, and its own configuration. Nothing in one site is visible to another.

Site properties:

PropertyDescription
NameHuman-readable identifier (e.g., "Production", "Acme Staging")
SlugURL-friendly unique identifier used in API paths and subdomains
DomainsOne or more custom domains that route to this site
UsersA separate user base — users in one site don't exist in another
SecretsSite-level encrypted configuration, inherited by all apps in the site
Frontend WorkersEdge logic deployed to this site's domains

Environment Types​

Sites are commonly used to represent different environments:

TypePurposeExample
ProductionLive customer-facing environmentacme-prod
StagingPre-release testing and QAacme-staging
DevelopmentActive development and experimentationacme-dev
TestingAutomated test environmentsacme-test

Custom Domains​

Multiple domains can point to a single site. For example, app.acme.com and acme.taruvi.cloud can both resolve to the same production site.

User Isolation​

Each site maintains its own user base. A user named alice@acme.com in the production site is completely separate from alice@acme.com in the staging site. They have different credentials, different roles, and different data.

Practical example: Acme Corp creates two sites — acme-prod for their live application and acme-staging for pre-release testing. Developers can test with sample data in staging without any risk to production.

What is an App?​

An App is a container for backend resources within a site. It groups related datatables, functions, storage buckets, roles, secrets, events, and analytics together under a single namespace.

Think of an app as a feature module or microservice boundary. An e-commerce platform might have a "Store" app for products and orders, and a "CMS" app for articles and media.

What Each App Contains​

Datatables​

Define data schemas, create tables, and perform CRUD operations. Datatables support 20+ filter operators, relationships between tables, aggregations, hierarchy and graph traversal, full-text search, schema migrations, and indexes.

See Data Service API and Data Service Quickstart.

Functions​

Serverless code execution in three modes:

  • PROXY mode — Forward requests to external services (Zapier, n8n, Make) as webhook proxies
  • APP mode — Execute Python code on Taruvi's runtime
  • SYSTEM mode — Built-in platform operations

Functions also support scheduled execution (cron jobs) and version control.

See Functions API.

Storage​

Cloud file storage organized into buckets. Each bucket supports path-based organization, public or private access controls, batch upload/download operations, MIME type restrictions, and storage quotas.

See Storage API and Storage Quickstart.

Roles & Policies​

Define custom roles per app and attach policy-based authorization rules for fine-grained access control. Policies determine which users can read, write, or manage specific resources.

See Role Management and Policy Management.

Secrets​

App-level encrypted configuration that inherits from site-level secrets. Secrets support JSON schema validation and sensitivity levels to control how values are exposed.

See Secret Management.

Events​

Subscribe functions to system events (e.g., "row created in table X") to build event-driven workflows. Events connect your datatables, functions, and external systems.

See Events API.

Analytics​

Run parameterized query templates against your data with secure, read-only execution. Analytics let you define reusable queries and expose them safely to dashboards or reporting tools.

See Analytics API.

Concrete Example​

Here's what a production site might look like for an e-commerce platform:

Site: Production
├── App: Store
│   ├── Datatables: Products, Orders, Customers
│   ├── Functions: Checkout Webhook, Inventory Sync
│   ├── Storage: Product Images Bucket
│   ├── Roles: Store Admin, Store Viewer
│   └── Events: Order Created → Notify Fulfillment
│
└── App: CMS
    ├── Datatables: Articles, Authors, Categories
    ├── Functions: Publish Workflow, Image Resize
    ├── Storage: Media Bucket
    ├── Roles: Editor, Contributor
    └── Events: Article Published → Clear Cache

Each app is independently configured — the Store app's roles don't affect the CMS app, and their datatables are namespaced separately.

Sites vs Apps — When to Use Which​

Use Sites for:

  • Environment isolation — Separate production, staging, and development so testing never touches live data
  • Customer isolation — In a multi-tenant SaaS product, give each customer their own site with fully separate data and users

Use Apps for:

  • Logical grouping — Organize related backend resources within the same environment (e.g., "Store" vs "CMS")
  • Feature modules — Treat each app as a self-contained feature with its own datatables, functions, and storage

Comparison​

AspectSiteApp
Data isolationComplete — separate database per siteShared database, separate tables per app
UsersSeparate user base per siteShared users within the site
SecretsSite-level secretsInherits site secrets + own app-level secrets
DomainsCustom domains per siteAccessed via site domain + app slug
Use caseEnvironments, customer tenantsFeature modules, microservices

Next Steps​