Multi-Tenancy

define.wtf is a multi-tenant platform, meaning one deployment serves many organizations (tenants). Each organization has its own isolated workspace, dictionary, users, and data. This section explains how multi-tenancy works and why it matters.

What is a Tenant?

A tenant is a single organization's workspace in define.wtf. Each tenant is completely isolated from others:

• Separate acronym dictionary
• Separate user list
• Separate settings and integrations
• Separate audit logs
• Separate data storage

Think of each tenant as a private define.wtf instance, even though they all run on the same platform.

Tenant Identification

URL-Based Routing (Subdomains)

Each tenant has a unique subdomain:

https://[slug].define.wtf

Where [slug] is your organization's unique identifier.

Examples:

https://acme.define.wtf           (Acme Corp's workspace)
https://engineering.define.wtf     (Engineering Team's workspace)
https://finance-dept.define.wtf    (Finance Department's workspace)
https://startup.define.wtf         (Startup Company's workspace)

How Subdomain Resolution Works

When a user visits https://acme.define.wtf:

1. Request hits define.wtf server
2. Server extracts subdomain: acme
3. Server looks up tenant with slug = "acme" in database
4. All subsequent requests in this session are scoped to this tenant

Custom Domains (Enterprise)

Some organizations use custom domains:

https://acronyms.mycompany.com  → routed to define.wtf

Custom domains are mapped to tenants via DNS CNAME configuration.

Tenant Model

Each tenant has these core attributes:

Tenant Settings

Each tenant can customize:

Data Isolation

Every database query includes a tenant filter. This is non-negotiable: define.wtf never returns data across tenant boundaries.

Example Queries

Finding all acronyms for a tenant:

SELECT * FROM acronyms
WHERE tenant_id = 'tenant-abc-123'
AND deleted_at IS NULL;

Finding users in a tenant:

SELECT * FROM users
WHERE tenant_id = 'tenant-abc-123'
AND status = 'active';

Finding definitions:

SELECT * FROM definitions
WHERE tenant_id = 'tenant-abc-123'
AND acronym_id = 'acr-456';

Notice every query has WHERE tenant_id = ... — this is essential for isolation.

API Responses Are Tenant-Scoped

When you call the API:

GET /api/v1/acronyms

You only get acronyms from your tenant, never from others. The tenant is determined by:

1. Which subdomain you're on (URL)
2. Or your authentication token (contains tenant ID)

Tenant Resolution in Middleware

define.wtf uses middleware to resolve the tenant on every request:

Request comes in to https://acme.define.wtf/api/v1/acronyms
  ↓
Middleware extracts subdomain: 'acme'
  ↓
Middleware looks up tenant: SELECT * FROM tenants WHERE slug = 'acme'
  ↓
Tenant ID added to request context
  ↓
All handlers use this tenant ID
  ↓
Database queries automatically filtered by tenant_id
  ↓
Response includes only data for this tenant

Multi-Tenant Scenarios

Scenario 1: Different Companies

Company A:

• Workspace: https://acme.define.wtf
• Team: 100 people
• Acronyms: 500

Company B:

• Workspace: https://startup.define.wtf
• Team: 20 people
• Acronyms: 200

Both use the same define.wtf platform but maintain completely separate dictionaries and never see each other's data.

Scenario 2: Department-Based Tenants

A large company might create separate tenants per department:

https://engineering.acme.com    → Finance department dictionary
https://finance.acme.com        → Finance department dictionary
https://hr.acme.com             → HR department dictionary

Each department maintains its own acronym dictionary relevant to their function.

Scenario 3: Environment-Based Tenants

Some organizations run separate instances:

https://define-staging.acme.com    → Test workspace
https://define-prod.acme.com       → Production workspace

This allows testing new acronyms without affecting the live dictionary.

Tenant Lifecycle

Creating a Tenant

When a new organization signs up:

1. Admin enters organization name and chooses a slug
2. Slug must be unique (not already taken)
3. Tenant is created in the database with initial settings
4. Workspace is ready to use at https://[slug].define.wtf
5. Admin is added as owner of the tenant

Managing Tenants

Tenant owners and admins can:

• Update settings — Organization name, color, logo (Settings → Branding)
• Configure integrations — SSO, SCIM, Slack, webhooks (Settings)
• Manage users — Add/remove/change roles (Settings → Members)
• View activity — Audit logs of all changes (Admin → Activity)
• Export data — Export dictionary (Admin → Export)
• Delete tenant — Permanent deletion of all data (Settings → Danger Zone)

Deleting a Tenant

When a tenant is deleted:

1. All data (acronyms, definitions, users, logs) is removed
2. Slug becomes available for reuse after 30 days
3. Data is purged from backups after 30 days
4. Workspace URL becomes inaccessible

This is permanent and cannot be undone.

Tenant Isolation Benefits

Privacy

Your team's acronyms and definitions are completely private. Other organizations cannot see them.

Security

Compromising one tenant's data doesn't expose other tenants. Each tenant is isolated at the database level.

Compliance

Easier to meet regulatory requirements (GDPR, HIPAA) because each tenant's data can be managed independently.

Customization

Each tenant can have different settings, integrations, and configurations without affecting others.

Scaling

Multiple organizations can use the same platform without performance impact on each other (though shared infrastructure means resource contention is possible).

Tenant and User Relationship

Users Belong to Tenants

Each user is associated with exactly one tenant:

Acme Corp (tenant-abc)
├── jane.doe@acme.com (Owner)
├── john.smith@acme.com (Admin)
├── sarah.chen@acme.com (Editor)
└── alex.patel@acme.com (Viewer)

Startup Inc (tenant-xyz)
├── alice@startup.com (Owner)
├── bob@startup.com (Editor)
└── charlie@startup.com (Viewer)

A user cannot have accounts in multiple tenants (though they can join additional tenants by being invited/provisioned separately).

Cross-Tenant Scenarios

Can a user log into multiple tenants?

Yes, but they must have separate accounts in each tenant:

1. User registers at https://acme.define.wtf with user@example.com
2. Later, user registers at https://startup.define.wtf with the same email
3. User must log in to each workspace separately (they have different accounts)
4. User sees different dashboards, different acronyms, different team members in each workspace

Can I view multiple tenants' data at once?

No. The platform is single-tenant from the user perspective. You're always viewing one tenant at a time.

API and Multi-Tenancy

Public API (/api/v1/)

The public API is tenant-scoped:

GET https://acme.define.wtf/api/v1/acronyms

Returns only acronyms from the acme tenant, determined by the subdomain.

Internal API (/api/internal/)

Internal admin endpoints are also tenant-scoped (used by your own systems only).

Authentication

API tokens are tenant-specific. A token for one tenant cannot access another tenant.

Considerations for Developers

Building Integrations

If you're building an integration with define.wtf:

1. Respect tenant isolation — Always use the correct subdomain/tenant ID
2. Store tenant info — Remember which tenant you're integrating with
3. Handle webhooks per-tenant — Each webhook is scoped to a tenant
4. Document tenant requirements — Make clear that your integration is per-tenant

Building Custom Apps

If building a custom app on top of define.wtf:

1. Understand tenant resolution — Know how your tenant is identified
2. Scope all queries — Always filter by tenant when accessing the database
3. Test isolation — Verify users cannot access other tenants' data
4. Consider cross-tenant features — If you need to compare tenants, ask support about enterprise features

Best Practices

• Understand your tenant — Know your workspace slug and ID
• Keep settings updated — Regularly review and update organization settings
• Manage users per tenant — Add/remove users at the tenant level, not globally
• Use SCIM for scale — If managing many users, use SCIM provisioning for automation
• Document custom domains — If using a custom domain, document the CNAME mapping
• Test in staging — Create a separate staging tenant before deploying to production

Future Considerations

When Multi-Tenancy Might Complicate Things

• Complex reporting — You can't easily compare metrics across tenants
• Single sign-on to multiple tenants — SSO is currently per-tenant
• Bulk operations across tenants — Not supported; must be done per-tenant

For enterprise needs beyond multi-tenancy, contact support@define.wtf.

See Also

• Roles and Permissions — Managing access within a tenant
• Audit Trail — Tracking changes within a tenant
• Admin Guide: Settings — Configuring your tenant